Skip to content

Architecture

Services

Service Responsibility Public entry point
clouddev-ide code-server, CloudCLI, Codex CLI, Claude Code CLI, launchpad, Caddy, and key-only OpenSSH Authenticated HTTPS and explicit SSH TCP proxy
clouddev-git Rootless Forgejo with registration disabled Forgejo sign-in, plus optional Git SSH
clouddev-postgres Forgejo metadata database Private networking only
clouddev-router OmniRoute dashboard, provider credentials, and model routing Private networking only; dashboard is proxied through the authenticated workspace

The launchpad, CloudCLI, VS Code, and both terminal agents run in the workspace service. They use the same filesystem. Forgejo and OmniRoute retain their own authentication. The workspace cookie is not a cross-service SSO token.

Shared workspace

The IDE service has one persistent volume at /workspace:

Path Contents
/workspace/home User settings, CLI configuration, CloudCLI state, and provider session artifacts
/workspace/projects Cloned repositories and project files
/workspace/system Service-owned persistent identities and host keys
/workspace/public-status Non-secret recovery summary for the launchpad

Forgejo, PostgreSQL, and OmniRoute use separate persistent storage. Volume-backed Railway services run one replica. No horizontal scaling is promised.

Browser and SSH boundaries

Caddy listens on the workspace's public HTTP port. Browser requests first pass a signed, HttpOnly workspace-cookie check. CloudCLI keeps its own Bearer token in the Authorization header. code-server and CloudCLI listeners remain on loopback. SSH accepts operator-provisioned public keys only and does not share the Forgejo Git key.

Railway private networking connects services but does not filter workspace egress. Coding agents can read files available to the workspace user and can make outbound requests. They may read the scoped inference key and regular Git key used for work. They receive no Railway token, Forgejo administrator credential, OmniRoute management secret, provider master key, Docker socket, or root privilege.

Session recovery

CloudCLI stores provider conversations and session artifacts on the persistent workspace volume. A durable task registry records task state. On startup, a task that was running becomes interrupted. Restarting a Railway service kills its in-memory process. CloudDev AI does not automatically replay a prompt or claim a killed process kept running. Resume only through a provider-supported user action.

See the threat model, data flow, and restore guide for more detail.