> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usekolaos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Infrastructure

Admins choose infrastructure during organization setup and manage it under **Organization**, then **Infrastructure**. The choice applies to every workspace in the organization.

| Choice | Where workstations run | Region |
| - | - | - |
| KolaOS Cloud | On nodes managed by KolaOS. | Choose EU or US during setup. |
| Your AWS account | On nodes KolaOS prepares in your AWS account. | Choose EU or US during setup. |
| Your servers | On servers you connect to the organization. | No region is assigned. |

The infrastructure and region cannot be changed by an organization admin after they are saved. Contact KolaOS if the saved choice needs to change.

## KolaOS Cloud

Choose **KolaOS Cloud** and a region, then create your workspace. KolaOS manages node capacity. A queued workstation may need to wait for capacity before it can start.

## Your AWS account

**1. Open the AWS setup link**

Choose **Your AWS account** and a region. Use an AWS identity with permission to create the access stack and its IAM resources, and open the link shown in KolaOS.

**2. Create the access stack**

Review the CloudFormation template and create the stack. The stack registers the account and creates roles KolaOS uses to prepare infrastructure. You do not paste AWS access keys into KolaOS.

**3. Check setup progress**

Return to KolaOS. Registration starts network and AI gateway setup, followed by nodes. The admin who connected the account receives setup updates by email.

Workspace setup can continue while AWS setup runs, but workstations need a ready node. If **AWS setup stalled** appears, check that the access stack completed in the intended account. The setup link lasts 24 hours unless an admin replaces it. Use **Open the AWS console** on **Infrastructure** when you need a replacement, and retry a failed setup step after fixing its reported cause.

## Your servers

> [!WARNING]
>
> Own-server installation is implemented but has not been verified on a real customer server.

### Requirements

| Requirement | Value |
| - | - |
| Operating system | Ubuntu 22.04 to 26.04. An LTS release is preferred. |
| Processor | x86-64 with hardware virtualization enabled. |
| Virtualization | `/dev/kvm` must exist. A cloud server needs nested virtualization. |
| Storage | At least 220 GiB free on the filesystem that holds `/var/lib`. |
| Permissions | Root access through `sudo`. |

The server needs outbound HTTPS on TCP 443 to `api.usekolaos.com`, `tools.usekolaos.com`, GitHub and its release hosts, `pkgs.zabbly.com`, `pkg.cloudflare.com`, `images.linuxcontainers.org` and the Ubuntu package mirrors. KolaOS requires no inbound connections to the server.

### Connect a server

In the setup flow, review the components and permissions, then choose **Continue to installation**. Copy the generated command from KolaOS and run it on the server. The command includes a join credential, so treat it as a secret and do not paste it into a shared issue or document.

The installer checks the host and release signature, installs Incus and the KolaOS services, and builds the workstation image. The node agent has administrative access to Incus. Wait for the node agent, virtualization, workstation image and AI gateway checks to pass.

If installation fails, use the error and setup log to fix the reported requirement. A setup with no joining server after 10 minutes shows a failure. Check that the join command is still valid and retry from **Infrastructure** rather than reusing an expired or revoked command.

### Rename a server

A server joins with its hostname as its name. To rename it, choose the pencil next to its name in **Infrastructure**. Only admins can rename a server, and the audit log records the old and new names.

### Disconnect a server

First, revoke the server in **Infrastructure** to end its KolaOS credentials and tunnel. Then inspect the removal commands on the server:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://tools.usekolaos.com/uninstall | sudo bash -s -- --dry-run
```

Without `--dry-run`, the script removes KolaOS services and configuration. Incus, workstation disks and the AI gateway remain unless you request their removal with the script's destructive options. Save needed work before removing any workstation storage.

## Access and content

Developers have root inside their workstations. Anything inside a workstation or on a laptop only deters; access enforcement must run outside those environments. For your own servers, administrators of the host also control Incus and workstation storage.

AI requests go to the providers the organization connects. For KolaOS Cloud and AWS infrastructure, prompt text is stored in KolaOS-owned regional storage. With **Your servers**, prompt text stays on the AI gateway on your server, and KolaOS keeps an index. An organization admin can retrieve the text through KolaOS. See [prompt records](https://docs.usekolaos.com/development/ai-tools.md#prompt-records).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.