Skip to content

Your first host

From a bare Linux box to a running workspace, in seven steps. The check comes first, and it changes nothing.

Bring-up, step by stepsynthetic host
$ bin/provision-host --host 203.0.113.10 --user ops --checkok203.0.113.10 is not this machineokkey-based ssh to ops@203.0.113.10oksystemdmissdocker absent (--install-prereqs installs it)okpython3 3.12.3missnode absent (--install-prereqs installs 22.x)okgit 2.43.0okcurl · jq · openssl · tarmisssudo will prompt (fine: the privileged phase runs on a tty)oknothing of ours is running here yet# 0 bad · 3 miss · nothing was changed

Check the host The check changes nothing on the host. It reports three states: ok, miss (fixable, or could not be tested) and bad.

Press a step to replay it. The host, addresses and output are synthetic; the commands are the real ones.

What the host needs

Ubuntu 24.04with systemd
Dockersystem daemon
Python 3.12standard library only
8 GB+memory
30 GB+disk
git · curljq · openssl · sudo

These are the figures Kodela runs on, not a sizing guarantee. Plan about 2 GB of memory per active workspace, and about 1 GB more for each person using the browser IDE. There is no Kubernetes, managed database or cloud account to set up: one Linux host is the whole install. More on the deployment page.

Getting the code: the repository is shared on request with pilot teams. It is not public, and there is no installer package yet. Ask about a pilot

Seven steps

  1. Check the host (preflight)

    Provisioning runs from a checkout on your own machine and reaches the host over key-based ssh; nothing on the host needs GitHub credentials. Start with the read-only check. It reports ok, miss or bad for each prerequisite and changes nothing.

    your machine
    $ bin/provision-host --host 203.0.113.10 --user ops --check

  2. Provision the serving tier

    This ships the commit you are on, installs prerequisites when you ask it to, builds the workspace image, installs the firewall's boot unit and starts the serving tier as a systemd unit. It prompts for the front-door and operator passwords; secrets never go on a command line.

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

    provision-host is new. Its happy path has not yet been recorded against a second machine. On the host itself, start-ui.sh brings the front door and console up by hand.

  3. Confirm it is ready

    Readiness answers 503 and names the failing check until everything is in place. bin/deploy verify exits 0 when the live tree is the commit you pushed.

    on the host
    $ curl -s http://127.0.0.1:5000/api/readyz
$ bin/deploy verify

  4. Create the first operator

    The serving tier creates the first operator from OPERATOR_EMAIL and OPERATOR_PASSWORD, once, and never overwrites a password changed later in the console. To create another operator, or reset one, run the command yourself on the host from the checkout. 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.

    on the host
    $ read -rs OPERATOR_PASSWORD && export OPERATOR_PASSWORD
$ python3 proxy.py create-operator --email you@example.com

  5. Sign in and create an organisation

    Open the console at /admin/ and sign in as the operator. Create an organisation: it gets its own network, egress in observe and the Guarded security level.

    ConsoleOrganisationsNew

  6. Invite a member

    Invite by email and pick a role: owner, admin, member or auditor. The invitation lasts 7 days. The person claims it and sets a password. Until mail is configured, the console shows you the link to send yourself.

    OrganisationsacmeMembersInvite

  7. Create a workspace and open it

    From the organisation's Workspaces tab, or on the host. Creation is refused unless the firewall has verified the organisation's network and a DNS gateway exists. The member signs in at /portal/ and opens it: a terminal, VS Code in the browser, the Git panel and the agent chat. Every outbound connection from this workspace on your host already goes through the egress proxy, in observe. (If your organisation later turns on members' own computers, egress there is observed, not enforced.)

    on the host
    $ bin/workspace-agent create --tenant acme --workspace dev01 \
    --owner dev@example.test --repo owner/name --ide

Know this first

  • TLS is yours to put in front. The front door ships without it and there is no automatic certificate. Use a TLS front end or a tunnel before anyone signs in over a network.
  • Egress starts in observe. It logs and lets through. Promote it to deny once the allowlist stops surprising you.
  • Mail is off until you configure SMTP, so invitation and reset emails do not arrive out of the box.
  • Nothing schedules backups. bin/backup exists; add the timer yourself.
  • The shared front-door password is not tied to a person until “require identity” is turned on. Turn it on once everyone has an account.

Next

Configure egressThe seven words

Verified against the main branch, 4 Oct 2026.