AI Dev Environments

1. Create the box

In the dashboard, go to Development → New. The form asks you for one decision:

• Source — a connected GitHub repo, any http(s) git clone URL, or a blank box. Pick Blank box if you haven't installed the GitHub App yet; you can clone from the terminal afterwards.

Everything else is behind Options, already defaulted, with the monthly price shown on the collapsed row:

• Name — leave blank and the box is named after its source, numbered if you already have one by that name.
• Where it runs — HostStack compute, or a machine your team has enrolled.
• Size — Standard (2 GB / 1 vCPU) by default. See Sizing.
• Companion services — fresh, empty managed Postgres / Redis / Meilisearch wired into the box's environment. Off by default.

Hit Create Dev Box. HostStack creates the private service, attaches a 10 GB /workspace volume, provisions any companions, and deploys. You land on the box's workspace while it provisions.

The dashboard wizard is the canonical creator, but not the only safe one. The CLI (hoststack dev new) and the MCP tool create_dev_environment create the same thing, and the minimum-size floor is applied server-side on every create path — a dev box below that floor runs out of memory the first time an agent and a build run together. There is deliberately no dev-box preset in the generic service wizard, though a generic service pointed at the dev-env image is floored the same way.

2. Open it

Every box lives in the dashboard's Development section. Switch between boxes from the rail, then use the tabs: Terminal, Tasks, Running, Metrics, Logs, Deploys, Setup, Settings.

The Terminal tab opens multiple tabs per box, each backed by a named tmux session inside the container. Detaching — navigating away, closing the laptop, losing signal — leaves whatever is running still running; reopening reattaches to it. That's what lets you kick off an agent and come back later.

The first shell of each boot prints hoststack-status: which engines are up and on which ports, the box's dev URL, agent login state, and which image build the box is on. Run hoststack-status any time to see it again.

From your own machine, hoststack dev new, hoststack dev list and hoststack dev delete cover lifecycle; run hoststack dev --help for the flags. Inside the box the CLI is already authenticated as you.

3. What's already inside

• Coding agents: claude (Anthropic Claude Code), codex (OpenAI Codex), and opencode (SST OpenCode) — all on PATH.
• MCP servers wired into all three agents: hoststack (your projects, services, deploys, databases, domains), poststack (email), filesystem, git, and chrome.
• A real browser: Google Chrome, driven headlessly. The agent can open the dev server it just started, screenshot it, read the console and network log, click through a flow and profile it — so it can check its own work instead of guessing.
• Five data engines, natively: dev-services up starts Postgres 17 (:5432), Redis (:6379) and Meilisearch (:7700). dev-services up mysql adds MariaDB (:3306, MySQL protocol) and dev-services up mongodb adds MongoDB (:27017) — opt-in, so you don't pay memory for engines you don't use. Four of them (Postgres, Redis, MariaDB, MongoDB) are also managed database engines here; MySQL is a fifth managed engine the image does not carry, and Meilisearch is our managed search product rather than a managed database.
• Every runtime we deploy: Node, Bun, Python and PHP (with composer and the WordPress/Laravel extension set) are built in. dev-runtime add go — or java, ruby, rust, erlang, elixir, dotnet — installs the rest onto the volume.
• Toolchain: git, GitHub CLI (gh), the authenticated hoststack CLI, ripgrep, fzf, jq, tmux, psql, redis-cli, mariadb, mongosh, curl/wget, zip/unzip, and the usual editors.
• A persistent /workspace volume — repos, agent logins, node_modules, installed runtimes and database data all live there and survive restarts.

There is no Docker daemon in a box. That's why dev-services and dev-runtime exist. Running docker or apt-get install prints the in-box alternative instead of a misleading error — and docker reads a docker-compose.yml in the current directory and tells you which of that file's services the box already provides.

4. Your agents are already wired

Agent logins are account-wide. The default you pick per agent under Settings → Coding Agents is seeded into every box on boot, so you sign in once — not per box. Those credentials are stored on your account encrypted at rest (AES-256-GCM). The HostStack MCP key is provisioned for you, so the agents' platform tools work with no manual key entry.

No saved login yet? Log in inside a box, then capture it to your account from Development → Setup:

claude /login             # device-code flow
codex login
opencode auth login

# then: Development -> Setup -> Capture from this box

On every boot the platform refreshes an orientation guide into all three agents' global instruction files — /workspace/.claude/CLAUDE.md, /workspace/.codex/AGENTS.md, ~/.config/opencode/AGENTS.md. It covers the native databases, the missing Docker daemon, the 64 MB /tmp and the pre-authenticated CLI, which is why an agent in a box doesn't reach for docker run postgres. It is written at user scope, so it never collides with a repo's own CLAUDE.md.

Ask for the browser in plain language — "start the dev server, open it, show me a screenshot", or "the login page 500s, check the network tab". Chrome starts lazily on the first browser tool call and costs roughly 300–400 MB while a page is open, so size up if you're also running an agent and a dev server on a 2 GB box. Each agent session gets a throwaway profile; run dev-browser up instead if you want one shared Chrome that stays logged into the app you're testing (profile on /workspace, DevTools on 127.0.0.1:9222).

5. Serve on port 3000 — your dev URL

Every box has a private, unguessable public URL that proxies to port 3000 inside the box. Start a dev server on 3000 bound to 0.0.0.0 and it's live at that URL; until something is listening there, our edge serves a branded "No app is listening on port 3000 yet" page with HTTP 503 rather than a bare proxy error. The box presets HOST=0.0.0.0, injects PORT=3000, and exports the URL as $HOSTSTACK_DEV_HOST.

The proxied port is hard-wired to 3000. Setting a different PORT does not re-point the URL — it just moves your server off the port the proxy reaches, so the box looks empty.

Dev servers (Vite, Next, Astro, …) reject requests whose Host header isn't allow-listed, so a plain run is refused at the dev URL even when bound to 0.0.0.0:

// Vite — vite.config.ts
export default defineConfig({
  server: { host: true, allowedHosts: ['.hoststack.dev'] },
})

// Next.js — next.config.js
// Use the literal wildcard: HOSTSTACK_DEV_HOST is undefined unless you've
// exported it, and [undefined] allow-lists nothing.
module.exports = { allowedDevOrigins: ['*.hoststack.dev'] }

6. Databases: three different things

• In-box engines (free, throwaway). dev-services up runs Postgres/Redis/Meilisearch — and mysql/mongodb on request — natively on /workspace. Local-only, trust auth, no password. PGHOST/PGUSER/PGDATABASE are preset so a bare psql just connects. If your app expects a different database name, run dev-services createdb <name> rather than editing its config.
• Companion managed databases (created with the box). The toggles in the create form stand up fresh, empty managed Postgres / Redis / Meilisearch and link them to the box, so their connection variables are injected into the container.
• An existing managed database (linked afterwards). The create form can only make fresh companions, but a dev box is a service, so you can link a database you already have. It applies on the box's next deploy.

# in-box, throwaway
dev-services up
dev-services createdb myapp
dev-services status

# link a managed database you already have (alias defaults from its name)
hoststack db link db_… --service <dev-box-id> --alias APP
hoststack deploy trigger <dev-box-id>

A link injects <ALIAS>_URL, _HOST, _PORT, _DATABASE, _USERNAME, _PASSWORD — plus the canonical DATABASE_URL (SQL engines), REDIS_URL or MONGO_URL, set only if you haven't defined them yourself. A Meilisearch link injects <ALIAS>_URL, _HTTP_ADDR and _MASTER_KEY. See Managed Databases.

7. Injected environment

HostStack sets a handful of variables in the container at boot. These are real environment variables, so under Bun/Node they take precedence over the same keys in a committed .env file — a committed PORT or DATABASE_URL is silently ignored. What's injected:

• PORT (3000) and HOSTSTACK_DEV_HOST — the listen port and public dev host.
• HOSTSTACK_* — HOSTSTACK_SERVICE_NAME (also your shell prompt label), service/project/team IDs, internal URL, deploy ID and branch.
• Connection variables for every linked database or search resource, per the section above.
• Anything you set yourself under Settings → Variables — including ANTHROPIC_API_KEY, OPENAI_API_KEY and POSTSTACK_API_KEY if you'd rather use API keys than a subscription login.

Run printenv in the box to see the live set. To point at the in-box engines instead, export the URL in your shell — a shell export overrides the committed .env.

8. The Setup tab

Development → Setup on a running box covers three things, without touching the terminal:

• Agent logins — pick which saved login this box uses, or capture the one you just made here back to your account.
• GitHub access — checks whether the team's GitHub App is connected and grants push. HTTPS clone and push are authenticated through it with no key, and SSH-style GitHub remotes (git@github.com:owner/repo.git) are rewritten to HTTPS so they use it too.
• Git identity — the name and email stamped on your commits, written through to /workspace/.gitconfig.identity.

9. Sizing

Boxes start at Standard (2 GB RAM / 1 vCPU) and go up through Large (4 GB / 2 vCPU) and XLarge (8 GB / 4 vCPU); the picker shows each tier's price. Smaller service tiers exist but are not offered for dev boxes and are raised to the floor server-side — a coding agent plus a build does not fit below 2 GB.

Rough budget: about 0.5 GB per coding agent after ~1 GB for the OS and your dev server, plus ~0.4 GB while the agent has a browser page open. Change the tier any time from Settings → General → Size. Memory and CPU apply live on the running container — no recreate, no dropped shells. If a box is OOM-killed the workspace header says so and offers the next tier up.

The /workspace volume starts at 10 GB and can be grown (never shrunk) from Settings → Storage. A larger disk applies on the next recreate — power the box down and resume it.

10. Power down, resume, and what persists

Power down from the workspace header stops the container so it stops consuming compute. Everything running in it — terminal sessions, tmux, in-flight agents — ends. /workspace is a persistent volume and is kept. Resume re-runs the box on its image in seconds.

A box runs until you power it down; nothing sleeps it for you, and a suspended box's dev URL does not wake it on visit — you resume it from the dashboard. Powering down stops the compute, not the bill — see Shipping and billing.

A recreate (power down → resume, or a redeploy) rebuilds the root filesystem from the image. Only /workspace survives, which is why runtimes, caches, agent logins, SSH keys and git config all live there. Anything you append to ~/.bashrc is lost; put it on /workspace and source it.

Code from your phone

The Terminal is built mobile-first. Install HostStack as a PWA (Add to Home Screen) or just open it in any mobile browser. Tap the terminal to bring up your keyboard; a soft-key bar gives you the keys phones lack — Esc, Tab, common Ctrl combos (Ctrl-C/D/Z/R/L), arrow keys and shell symbols. The view tracks the on-screen keyboard so your prompt is never hidden. Kick off an agent, lock your phone, come back later — the session keeps running on our infra.

An Attach button (and drag-drop or paste on desktop) uploads a file into /workspace/.uploads/ and pastes its path at the cursor, so your agent can read a screenshot or a log by path. Files are capped at 16 MB each.

Shipping and billing

A dev box shares the same git and deploy plumbing as the rest of HostStack: have your agent commit and git push, and the push hits your service's normal deploy webhook. The in-box hoststack CLI is already authenticated as the box owner, so hoststack services, hoststack logs and hoststack deploy trigger need no login step.

A box bills like the private service it is — the size tier you pick, plus the /workspace volume's per-GB-month storage, plus any companion databases (those bill as managed databases). A box on a machine your team enrolled has no compute charge, just the flat bring-your-own environment fee. Powering a box down frees the machine, not the invoice line: a provisioned box is billed until you delete it. Delete it when you're done with it; power down only to stop it consuming compute and memory.