Start here¶
CloudDev AI runs as one private workspace service and three independent supporting services. It is a single-user deployment, not a shared SaaS workspace.
Choose a path¶
Run the local stack¶
Requirements: Docker Compose v2, Node.js 24, and uv for the documentation build.
./scripts/dev-env.sh
docker compose config --quiet
docker compose up --build
Open http://localhost:8080/ and sign in with the local CODE_SERVER_PASSWORD. Open the launchpad to find CloudCLI, browser VS Code, Forgejo, OmniRoute, and the SSH connection details. Do not commit .env, private keys, or the local secrets/ directory.
Prepare a Railway deployment¶
- Review the release status and the security release hold.
- Use a new Railway test project in the intended personal workspace. Do not apply this configuration to an unrelated project.
- Review
railway config plan. Only apply a reviewed plan to that dedicated project. - In the Template Composer, set the EU West region, public HTTPS domains, TCP proxies, ten independent generated secrets, and the operator's Ed25519 public key. Keep PostgreSQL and OmniRoute private.
- Check the full Composer variable inventory and follow the deployment runbook.
The deployment instructions describe expected configuration. They do not establish that a live Railway deployment has those settings.
First login and provider setup¶
- Sign in to the workspace using its generated browser password.
- Create CloudCLI's single local account on first use.
- Sign in to Forgejo with the bootstrap account, change its password, and create a regular user with a private repository.
- Run
git-setupin the workspace and add its public key to that regular Forgejo user. - Sign in to OmniRoute, change its bootstrap password, add your provider account, and create a restricted inference key.
- Run
ai-setup, choose an available model, then checkai-statusandai-models.
No provider API key is generated for or included in the public template. Never put the provider master key in workspace variables or an agent environment.
Connect from each device¶
- Native VS Code connects with Remote-SSH using the operator's private key and the workspace SSH endpoint. Railway's
railway sshcommand is not the Remote-SSH transport. - Browser VS Code is served at
/vscode/after workspace authentication. - The mobile agent interface is served from the authenticated workspace origin. It uses the same projects and can reopen provider sessions supported by the upstream CLI.
Closing a client does not stop a detached task. Restarting the workspace stops in-memory processes. Review the task registry and use only the upstream-supported manual resume path.
Keep the evidence straight¶
Local tests, a GitHub Pages build, a live Railway deployment, a Marketplace listing, and a successful restore are separate checks. The operations control plane shows which configuration surface owns each setting and which gates are still open.