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, see 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, destroy; show status and ports; set port visibility; mint preview links; forward a port to 127.0.0.1; open a shell; follow the event log. |
| Phone | Coming soon. |
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.
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.