Install on your host

What this installs

The serving tier: the console process that everyone reaches, the front door in front of workspace terminals and IDEs, the brokers that keep credentials out of containers, the egress proxy and firewall, and the workspace image. State lives on the host in one SQLite store and a state tree beside it. There is no Kubernetes, managed database, cloud account or installer package.

It does not install high availability, a second host, scheduled backups or outbound mail. Each has its own section below, and each is off until you set it up.

What the host needs

These are the figures Kodela runs on, not a sizing guarantee. No workspaces-per-host figure is stated. Workspaces are capped at 2 GB memory, 2 CPUs and 512 processes each.

Docker in a workspace is off until an organisation allows it (workspace_docker_allowed). docker_full_runtime is a host setting, auto by default: it picks Sysbox when the host has it and never resolves to privileged, which an operator must set explicitly and under which the firewall and no-credentials guarantees no longer hold for that workspace. Each new workspace also gets its own Postgres by default; a host without the Postgres image skips it and says why.

Ports the tier claims on the host. Only 80 and 443 should face people, and those belong to your TLS front end or tunnel, not to Kodela.

Get the code

The repository is shared on request with pilot teams. It is not public, there is no installer package, and nothing on the host needs GitHub credentials: provisioning ships the commit you are on from your own checkout.

Check the host first

From your checkout, on your own machine. It reaches the host over key-based ssh and changes nothing. Each line is ok, miss (fixable, or could not be tested) or bad.

$ bin/provision-host --host 203.0.113.10 --user ops --remote-dir kodela --check

It reports the OS and kernel, systemd, whether your user can use Docker, Python, Node (20 or later), git and the small tools, free disk and memory against the verified figures, whether ports 5000, 8080, 8083, 8071, 8072, 8074 and 3128 are free on any address, and whether an older tier or its containers are already running. The ssh user must not be root, must be allowed sudo, and ends up in the docker group.

A pass here is only a pass for what it tested. The check prints the OS but does not refuse one it was not verified on.

Provision

From another machine, over ssh (recommended)

bin/provision-host ships this commit as a git bundle, writes three env files, builds the workspace image, publishes the tree every workspace mounts, builds the console, installs the serving-tier unit and the firewall unit, starts the tier and checks it. It refuses to run against the machine it runs on.

$ bin/provision-host --host 203.0.113.10 --user ops --remote-dir kodela \
    --base-url https://kodela.example.com \
    --operator-email you@example.com --install-prereqs

Exit code 0 means every phase that ran passed; 1 is a usage error or a local guard; 2 is a remote phase that failed, and the output names it.

provision-host is new. Its happy path has not yet been recorded end to end against a second machine. If the GitHub CLI is signed in on the host it also runs an extra tooling installer; the serving tier does not need it.

On the host itself

For a single machine you are signed in to. It is the same sequence provision-host runs, by hand: pick The host itself in the builder above for the full list. The parts that matter:

1. Decide the state tree and export it in every shell. export AGENT_STACK_SHARED="$PWD/.agent-stack-data" from the checkout. The units read the same value from an env file.

2. Write three env files, mode 0600, in ~/.config/agent-stack/: door.env (front-door user, password, bind to loopback), admin.env (the first operator) and cluster.env (the state tree).

3. Build the workspace image and publish the tree. The build context is the repository root. bin/deploy push needs sudo because the published tree is root-owned.

4. Install the serving-tier unit from config/systemd/ with your user, home, checkout path and base URL, plus the firewall unit, then enable both.

The first operator

A fresh install has no sign-in and no self-service signup. The serving tier creates the first operator from OPERATOR_EMAIL and OPERATOR_PASSWORD in admin.env, once, and never overwrites a password changed later in the console. To add another operator or reset one, run it yourself from the checkout on the host. The password comes from --password or the OPERATOR_PASSWORD variable and must be at least 12 characters; reading it into the variable keeps it out of your shell history.

$ cd ~/kodela && export AGENT_STACK_SHARED="$PWD/.agent-stack-data"
$ read -rs OPERATOR_PASSWORD && export OPERATOR_PASSWORD
$ python3 proxy.py create-operator --email you@example.com

Run it with the server's state tree. In a shell whose AGENT_STACK_SHARED differs from the running tier's, it writes to a different, or empty, store, and the console never sees the account.

Then sign in at /admin/ on your origin.

The systemd units

The whole serving tier is one unit whose ExecStart is start-ui.sh: it starts the front door, portal, brokers and egress proxy, verifies each, then runs the console process. systemd owns every child, so stopping the unit stops the tier. Configuration comes from env files, not from edits to the unit.

# which unit serves the tier, and is it up
$ systemctl list-units --all 'agent-stack-*'
$ UNIT=$(grep -l 'ExecStart=.*start-ui' config/systemd/*.service); N=$(basename "$UNIT")
$ systemctl is-active "$N" agent-stack-firewall
$ systemctl cat "$N"

The firewall unit (agent-stack-firewall.service) runs once at boot, as root, after the front door is up. The firewall rules are never saved by iptables, so without this unit a reboot silently drops them while status and verify kept reporting healthy until then.

First organisation and workspace

1. Create the organisation. In the console: ConsoleOrganisationsNew It gets its own network, egress in observe and the Guarded security level. The slug must match ^[a-z0-9][a-z0-9-]{0,30}$.

2. Invite its owner, or yourself as a member. Owner is an operator grant. See Invitations.

3. Create a workspace. From the organisation's Workspaces tab, or on the host. Warm sudo first: creation extends the firewall to the organisation's network and refuses if it cannot.

   on the hostCopy

   $ sudo -v
   $ bin/workspace-agent create --tenant acme --workspace dev01 \
       --owner you@example.com --ide --repo owner/name

4. Open it. The owner signs in at /portal/: terminal, VS Code in the browser (with --ide), the Git panel and the agent chat. Every outbound connection from this workspace on your host already goes through the egress proxy, in observe.

Verify it works

$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5000/healthz
$ curl -s http://127.0.0.1:5000/api/readyz | jq '.ready, .checks'
$ bin/deploy verify
$ bin/whats-running
$ bin/front-door status

Good looks like: healthz answers 200; readyz says "ready": true with every check ok (it answers 503 and names the failing check otherwise); deploy verify exits 0; the unit's startup banner says BUILT BUNDLE and, on an https origin, does not say PLAIN HTTP. What each readyz check means.

Upgrade

An upgrade is publishing a newer commit. From your machine, re-run provision-host with --ref: it ships, publishes, rebuilds and restarts. On the host, take a backup, publish, verify and restart the unit. Every restart is a short outage. When the store is newer than the code, API calls are refused with a sentence until the code catches up.

$ N=$(basename "$(grep -l 'ExecStart=.*start-ui' config/systemd/*.service)")
$ bin/backup create --volumes && bin/backup verify <name>
$ bin/deploy push --ref <ref> && bin/deploy verify --ref <ref>
$ sudo systemctl restart "$N"
$ curl -s http://127.0.0.1:5000/api/readyz | jq .ready

Rolling back is bin/deploy rollback --ref <ref>. The full runbook is on Operate.

Uninstall and wipe

There is no uninstall command. This is the procedure, and its order matters: units first (a watchdog respawns processes every ten seconds while the unit runs), the firewall before the networks, the state tree last. Match containers by label and image, never by name, and never use docker system prune, volume prune or network prune on a shared box.

1. Enumerate first; change nothing. Which state tree the unit uses, which units, containers, volumes and networks exist.

   on the hostCopy

   $ cd ~/kodela && export AGENT_STACK_SHARED="$PWD/.agent-stack-data"
   $ N=$(basename "$(grep -l 'ExecStart=.*start-ui' config/systemd/*.service)")
   $ systemctl show "$N" -p Environment -p ExecStart -p User
   $ systemctl list-unit-files 'agent-stack-*'
   $ docker ps -a --filter label=agent-stack.workspace --format '{{{{.Names}}}}\t{{{{.Status}}}}'
   $ docker volume ls --format '{{{{.Name}}}}' | grep -E '^ws-.*-home$|^agentstack-'
   $ docker network ls --format '{{{{.Name}}}}' | grep -E '^agentstack-'

2. Back up, and copy the archive off the host. bin/backup create --volumes.

3. Stop and remove the units.

   on the hostCopy

   $ sudo systemctl disable --now "$N" agent-stack-firewall
   $ sudo rm -f /etc/systemd/system/agent-stack-*.service
   $ sudo rm -rf /etc/systemd/system/agent-stack-*.service.d
   $ sudo systemctl daemon-reload && sudo systemctl reset-failed

4. Bring the firewall down, then remove containers and networks.

   on the hostCopy

   $ sudo -E bin/egress-firewall down
   $ docker ps -aq --filter label=agent-stack.workspace | xargs -r docker rm -f
   $ docker rm -f agentstack-front-door agentstack-access-auth 2>/dev/null
   $ docker ps -a --format '{{{{.ID}}}}\t{{{{.Image}}}}' | grep 'cloudflare/cloudflared' | cut -f1 | xargs -r docker rm -f
   $ docker network ls --format '{{{{.Name}}}}' | grep -E '^agentstack-' | xargs -r docker network rm
   $ docker images --format '{{{{.Repository}}}}:{{{{.Tag}}}}' | grep '^agent-stack/' | xargs -r docker rmi -f

5. The irreversible step: home volumes. Every developer's work is in ws-<organisation>-<workspace>-home. Look at the list, confirm the backup is off the host, then remove them.

   on the hostCopy

   $ docker volume ls --format '{{{{.Name}}}}' | grep -E '^ws-.*-home$'
   $ docker volume ls --format '{{{{.Name}}}}' | grep -E '^ws-.*-home$' | xargs -r docker volume rm

6. Remove the state tree, the env files and the checkout. This deletes the store (accounts, organisations, workspaces), the credential store and the audit chain.

   on the hostCopy

   $ rm -rf "$AGENT_STACK_SHARED"
   $ rm -rf ~/.config/agent-stack ~/kodela

7. Clean up what lives elsewhere. A Cloudflare tunnel, its Access application and DNS record, a GitHub App and any AI provider sign-ins made through the console still exist on those services. Delete or revoke them there.

Docker, Python, Node and the other prerequisites are left in place, ready for a clean reinstall.

More than one host

Worker hosts (a Postgres placement store and mutual-TLS worker enrolment) are built and off by default. They have been seen working only in development, and their test suite is currently failing. Leave the setting unset: off is the single-host path, byte for byte. A workspace cannot be moved between hosts.

Members' own computers

Separate from worker hosts, and also off by default. You grant it per organisation (personal_hosts_allowed); the organisation then turns it on (personal_hosts_enabled); each member adds their computer on Your computers in the portal and pastes the one command it shows, which runs bin/personal-host-install.sh on Linux or WSL, or bin/personal-host-install.ps1 on Windows. The agent connects out, needs no sudo, and updates itself. A computer that has not connected within its lease (30 days by default) is disabled. The steps are in Workspaces.

Workspaces run on your Kodela host. If a platform operator grants it and your organisation turns it on, a member's own computer can host their workspaces too. There, internet access is observed, not enforced; DNS filtering is not enforced; the source on its disk is readable by whoever uses it; and Docker is not available. Tested end to end only on Windows (Linux laptops up to enrolment; Mac only in a simulation).

Troubleshooting

What it does not do yet

• No installer package, Helm chart or Compose file. The install is a checkout and the steps above.
• No ACME. Kodela serves plain HTTP unless you put a TLS front end or tunnel in front.
• provision-host is unproven end to end. Its own header marks it unproven against a second machine. The by-hand path is the fallback.
• Nothing schedules backups. bin/backup exists; you add the timer.
• No high availability. The control plane is one SQLite file on one host. Worker hosts are built and off.
• Air-gapped install is partial. Everything is version-pinned and images move with docker save; there is no offline bundle or mirror.
• Mail is off. Invitations and password resets are not delivered until you configure SMTP.
• Security starts permissive. Egress starts in observe, and the shared front-door password is accepted until “require identity” is on.

Related

Verified against the main branch, 4 Oct 2026.