Projects & Environments
Give the agent a real machine — a managed VM or your own server — and attach to it from the desktop, the CLI or the hub.
An environment is a machine where the codai agent actually works: shell, files, builds and dev servers. A small daemon, codaid, runs on it and keeps one outbound WebSocket to the relay (wss://relay.codai.ro) — the machine never opens a listening port. Your devices attach through the same relay, so tools run in the environment while you watch and steer from wherever you are.
desktop / CLI / hub gateway ai.codai.ro (projects, environments, members, ports)
│ attach, terminal, ports ───▶ relay relay.codai.ro (daemon + client WebSockets, presence)
│ https://3000-<slug>.preview.codai.ro ─▶ │ preview router
▼ outbound WebSocket, never inbound
environment (managed VM or your own server)
codaid: shell · files · terminals · ports · git state · build lockVocabulary
| Object | What it is |
|---|---|
| Project | A repository plus its settings: repo_url, default_branch, optional devcontainer_path, and an isolation mode that decides how developers share machines. Owned by you, optionally attached to an org you administer. |
| Environment | One machine inside a project. Has a globally unique slug (it becomes the preview hostname), a provider, a state, an idle timeout and, for managed machines, a size and an hourly rate. |
| Member | A person with a role on one environment: owner ≥ maintainer ≥ developer ≥ viewer. Each member gets their own Linux account and a block of 100 ports inside the machine. |
| Port | A port you publish with a visibility (owner, org, authenticated, public). Published HTTP ports get a preview URL. |
| Secret | An ENV_STYLE value stored sealed; names can be listed, values are never returned. |
| Event | An append-only audit row: every state change, enrolment, member, port and secret change. The last 20 appear on the environment page. |
Two ways to get a machine
| Managed | Bring your own (BYO) | |
|---|---|---|
| Who provisions it | codai, on OpenStack (Cloudify, EU) or Hetzner Cloud | You — any Linux server you control |
How codaid gets there | Installed and enrolled by cloud-init, automatically | You run the installer with a one-time token |
| Start / stop | Yes, plus idle auto-stop | No — the machine is yours; archive or destroy only |
| Price | Per second of runtime, from your wallet | Free |
| Availability | Rolling out — feature-gated per account | Open to every key |
Details: install on your own server, managed environments, billing.
Attach from your devices
| Surface | What you can do today |
|---|---|
| Hub — hub.codai.ro/projects | Create projects and environments (BYO and managed), start/stop/archive/destroy, generate an enrolment token with the install command, manage members and your SSH key. The environment page shows forwarded ports, secret names, agent tasks, SSH access, this month's compute cost and the last events. |
| Desktop — Environments view (Alt+5 in the Developer skin, Ctrl+5 in the Assistant skin) | Attach the agent to an environment, open a terminal in it, see listening ports and change their visibility, copy or open preview URLs, create a BYO environment and enrol it. |
CLI — codaid env … | List, create, start, stop, archive, destroy; show status and ports; set or remove port visibility; mint preview links; forward a port to 127.0.0.1; open a shell; SSH in with a 12-hour certificate (env ssh, env ssh-ca); queue and follow agent tasks (env tasks list, create, get); manage members (env members list, add, role, remove) and secrets (env secrets list, set, rm); follow the event log. |
| Phone (Android) | Environments screen: list your environments, start and stop managed ones, open preview links. |
| MCP | Tools for agents: list_projects, list_environments, get_environment, start_environment, stop_environment, list_environment_ports, create_environment_task, list_environment_tasks, get_environment_task. Destroying environments and reading or writing secrets are deliberately not exposed over MCP. |
When the desktop agent is attached, the agent loop runs on your device and its tools run in the environment — the composer shows in <name>. Running the whole loop inside the environment (headless) is coming soon.
Preview hosts (https://{port}-{slug}.preview.codai.ro) and the relay (wss://relay.codai.ro) are served directly by codai's Google Cloud load balancer; Cloudflare only answers DNS for them and does not proxy the traffic.
Lifecycle at a glance
BYO: pending ──enrol──▶ enrolling (online / offline = daemon presence on the relay)
managed: creating ──VM up──▶ enrolling ──▶ running ⇄ stopping ─▶ stopped ─▶ archiving ─▶ archived
(idle / budget / funds)
any state ──destroy──▶ destroying ──▶ destroyed (BYO: straight to destroyed)A BYO environment has no provider step, so destroy lands on destroyed at once (and revokes the daemon's key) and archive on archived.
For a BYO machine the stored state stays enrolling after enrolment; whether it is reachable right now is the relay's presence (online), which drops 45 seconds after the daemon's last heartbeat.
Next: install codaid on your own server or create a managed environment.
Last updated: