AI dev environments

What a dev box is

A dev box is a private HostStack service running our hoststack/dev-env image, with a persistent /workspace volume. It provisions, resizes, powers down and bills like any other service — there is no separate product to learn. You open a terminal into it from the dashboard, start an agent, and can walk away: the session keeps running.

Moving an existing project in? See Move your dev environment for what moves cleanly and what doesn't.

Create a box

1. Open Development and click New dev box

   Development is in the dashboard sidebar. Your email address has to be verified before you can create a box.

2. Pick a source

   GitHub repo clones a repository your team has connected. Clone URL takes any http(s) git URL. Blank box starts empty — pick it if you haven't connected GitHub yet, and clone from the terminal later. A repo is cloned into /workspace/<repo> on the box's first boot.

3. Name it, or don't

   Leave Name blank and the box is named after its source, numbered if you already have one by that name.

4. Check the options

   Options is collapsed, with the monthly price on the row. Inside: Where it runs (HostStack compute, or a machine your team enrolled), Size (Standard by default — see Size and storage) and Companion services: fresh managed Postgres, Redis or Meilisearch wired into the box's environment. Companions are off by default, billed separately and deleted with the box.

5. Click Create dev box

   HostStack creates the service, attaches a 10 GB /workspace volume, creates any companions and deploys. You land on the box while it provisions.

The CLI and the MCP server create exactly the same box:

# From a connected GitHub repo (id from: hoststack github repos)
hoststack dev new --github-id 42 --db postgres,redis

# From any http(s) clone URL, on a bigger box
hoststack dev new --repo https://github.com/acme/my-app.git --plan large

# Blank
hoststack dev new --name scratch

Create a standalone dev box from my GitHub repo acme/my-app,
with a companion Postgres.

(Tool: create_standalone_dev_environment)

Every create path — dashboard, CLI and MCP — raises a size below Standard to Standard on the server, because an agent and a build don't fit in less than 2 GB.

From an existing service

To reproduce a bug in a deployed app, spin a box up from the service: its repo is cloned, its environment variables are copied, and its linked database is cloned so the box never touches production data. This is a CLI and MCP flow; the dashboard creates standalone boxes only.

hoststack dev create --service svc_...
# --no-db skips the database clone

Spin up a dev box from svc_... so I can reproduce the checkout bug.

(Tool: spin_up_dev_environment)

Open it

Every box lives under Development. Pick one from the rail on the left; All dev boxes at the top of the rail is the fleet view. A box has these tabs:

Leaving a terminal — navigating away, closing the laptop, losing signal — leaves whatever runs in it running. Coming back reattaches to the same tmux session. That's what lets you start an agent and check on it later.

The first shell after each boot prints hoststack-status: which engines are up and on which ports, the box's dev URL, which agents are signed in, and which image build the box runs. Run it again any time.

What's inside

A box has no Docker daemon, which is why dev-services and dev-runtime exist. Running docker prints what to use instead — and if there's a docker-compose.yml in the current directory, it tells you which of that file's services the box already provides. apt-get install does the same: it can't work here, and anything it installed would be gone after the next restart.

Agents, logins and permissions

Agent logins belong to your account, not to a box. Save one per agent under Settings → Coding agents and it is seeded into every box you create, so you sign in once. Saved logins are stored encrypted. The HostStack MCP key is provisioned for you, so the agents' platform tools work with no setup.

No saved login yet? Sign in inside a box, then save it to your account from Development → All dev boxes → Shared setup → Agent logins, with Capture next to that box:

claude /login          # then: Shared setup → Agent logins → Capture
codex login
opencode auth login

On every boot the box writes an orientation guide into each agent's global instructions — /workspace/.claude/CLAUDE.md, /workspace/.codex/AGENTS.md and ~/.config/opencode/AGENTS.md. It tells the agent about the native databases, the missing Docker daemon, the small /tmp and the signed-in CLI, which is why an agent in a box doesn't reach for docker run postgres. It sits at user scope, so it never collides with a repo's own CLAUDE.md.

The browser

Ask for it in plain words: "start the dev server, open it and show me a screenshot", or "the login page returns 500 — check the network tab". Chrome starts on the first browser tool call, not when the agent starts, and costs about 0.4 GB while a page is open — size up if an agent, a dev server and the browser share a 2 GB box.

By default each agent session gets its own throwaway browser profile, so it's never signed in to anything. The Browser tab shows a separate, shared Chrome whose profile lives on /workspace and survives restarts. Sign in to a site there yourself, then run dev-browser share on and the box's agents use that browser — and every session in it — instead. It's opt-in per box, and dev-browser share off turns it back off. The browser's DevTools port stays bound to 127.0.0.1 and is never exposed.

Serve your app on the dev URL

Every box has a public, unguessable URL of the form dev-….hoststack.dev that proxies to port 3000 inside the box. Start a dev server on 3000, bound to 0.0.0.0, and it's live there. Until something listens, the URL serves a "No app is listening on port 3000 yet" page with HTTP 503. Copy the URL, or click Open app, in the box's header.

The box sets PORT=3000 and HOST=0.0.0.0, and puts the dev URL's host name in HOSTSTACK_DEV_HOST. The proxied port is fixed at 3000: a server on another port isn't reachable from the URL, and PORT set under Variables is overridden.

Dev servers such as Vite, Next.js and Astro refuse requests whose Host header isn't on an allow-list, so a plain vite is rejected at the dev URL even when it listens on 0.0.0.0. Allow the HostStack dev domain:

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

// next.config.js — and start it with: next dev -H 0.0.0.0
module.exports = { allowedDevOrigins: ['*.hoststack.dev'] };

Databases

A box can use three kinds of database, and they are for different things:

# In-box
dev-services up                  # postgres :5432 · redis :6379 · meilisearch :7700
dev-services up mysql mongodb    # MariaDB :3306 · MongoDB :27017
dev-services createdb myapp      # a Postgres role + database your .env expects
dev-services status

# Link a managed database you already have; it applies on the next deploy
hoststack db link db_... --service svc_... --alias APP
hoststack deploy trigger svc_...

In the box, PGHOST, PGUSER and PGDATABASE are preset, so a bare psql connects. Engines you started come back on their own after a restart; dev-services down stops them for good.

A linked database injects <ALIAS>_URL, _HOST, _PORT, _DATABASE, _USERNAME and _PASSWORD, plus DATABASE_URL (Postgres, MySQL, MariaDB), REDIS_URL or MONGO_URL unless you've set those yourself. A linked Meilisearch injects <ALIAS>_URL, _HTTP_ADDR and _MASTER_KEY. See Managed databases.

Environment variables

These are real environment variables in the container. Bun's and dotenv's .env loading doesn't override a variable that's already set, so a PORT or DATABASE_URL in a committed .env is ignored while the injected one exists. printenv shows the live set; an export in your shell overrides both.

PORT

The port the dev URL proxies to. Always 3000 for a dev box.

Default: 3000

HOSTSTACK_DEV_HOST

The dev URL's host name, for a framework's allowed-hosts list.

HOSTSTACK_*

HOSTSTACK_SERVICE_NAME (also your shell prompt), HOSTSTACK_SERVICE_ID, HOSTSTACK_PROJECT_ID, HOSTSTACK_TEAM_ID, HOSTSTACK_DEPLOY_ID and HOSTSTACK_BRANCH.

Linked resources

Connection variables for every linked database or search index, as above.

Your own

Anything you set under Settings → Variables — for example ANTHROPIC_API_KEY or OPENAI_API_KEY if you'd rather use an API key than a subscription login. Changes apply on the next deploy.

Shared setup

Development → All dev boxes → Shared setup holds what is yours across every box you created, rather than one box's settings:

Agent logins

Which saved login each box uses, and Capture to save a login made in a box to your account. Claude Code and OpenCode share one login file between your boxes on the same machine — sign in on one and they're all signed in. Codex keeps a login per box, because its token rotates and copies would invalidate each other.

GitHub access

Whether your team's GitHub App is connected and can push. HTTPS clone and push to GitHub go through it with no key, and git@github.com: remotes are rewritten to HTTPS so they use it too.

Git identity

The name and email on your commits, stamped into every running box (stopped ones pick it up on their next start). Until you set one, a box uses the name and email on your HostStack account.

There's no form for SSH keys. For a non-GitHub remote over SSH, put the key in /workspace/.ssh/ from the terminal with mode 600 — ~/.ssh points there, so it survives restarts. Move your dev environment has the commands.

Size and storage

The create form offers these sizes. Standard is the default and the smallest a box can be:

The agent estimate reserves about 1 GB for the system and your dev server and allows about 0.5 GB per agent; an agent driving the browser needs about 0.4 GB more. The Pro sizes run alone on a dedicated machine, which keeps about 1.5 GB of the RAM for itself.

Change size under Settings → General → Size. Memory and CPU change live on the running container — no restart, no lost shells. If a box runs out of memory, its header says so and offers the next size up.

/workspace starts at 10 GB. Grow it — it can't shrink — under Settings → Storage; a bigger disk applies after the box next restarts, so power it down and resume it.

Power down, resume and what persists

Power down in the box's header stops the container. Everything running in it ends — shells, dev servers, agents mid-task — and /workspace is kept. Resume starts it again, and a box you powered down stays down until you do.

A box nobody is using — no terminal attached, no agent or build running — is powered down after a while to free its compute. Opening it again, in the dashboard or with a new terminal, wakes it: the workspace shows it starting and the terminal opens once it is up. Waking takes a team owner or admin, the same as Resume. Visiting the dev URL of a powered-down box doesn't wake it.

Powering down, resizing the disk and an image update all recreate the container from the image. Only /workspace survives, which is why runtimes, caches, agent logins, SSH keys, git config and database data all live there. A line you add to ~/.bashrc is lost; keep it on /workspace and source it.

Your agent conversations come back. Transcripts are on /workspace, and the box records which one belonged to which terminal tab and directory. On the next boot it reopens each tab and resumes its conversation — the agent shows its transcript and waits for you. Dev servers, background jobs and half-run commands are not restarted. dev-session list shows what's remembered, and dev-session off turns it off for a box. The Sessions tab lists the same, and the fleet view's Sessions tab lists it for every box, including powered-down ones.

Code from your phone

The Terminal works in a mobile browser, and HostStack installs as a web app from your browser's Add to Home Screen. Tap the terminal to bring up the keyboard. A key bar gives you what phone keyboards lack: Esc, Tab, ⇧Tab, arrows, ^C ^D ^Z ^R ^L and common shell symbols, plus Paste, Attach and Mic for Claude Code's voice input. Start an agent, lock the phone and come back later.

Attach — or drag and drop, or paste, on a desktop — uploads a file into /workspace/.uploads/ and pastes its path at the cursor, so an agent can read a screenshot or a log. Files can be up to 16 MB each.

Focus mode hands the workspace the whole window: the dashboard's sidebar, top bar and phone tab bar step aside, which on a phone is a full row more terminal. Toggle it with the panel button beside the workspace tabs or Ctrl+Alt+F (⌃⌥F on a Mac). Search (Ctrl+K) and notifications stay within reach, and your browser remembers the choice.

Commands in the box

hoststack-status

What's running now: engines and ports, dev URL, agent logins, image build.

dev-services

up [mysql|mongodb], down, status, createdb <name> [owner] — the in-box databases.

dev-runtime

list, add go[@1.24], remove, which — language runtimes, installed onto /workspace. Elixir needs dev-runtime add erlang first, which builds from source and takes a few minutes.

dev-browser

share on|off — whether agents use the shared, signed-in browser.

dev-agent

yolo on|off, status — Claude Code's permission mode.

dev-session

list, restore, off — which conversations come back after a restart.

dev-ci

Runs a repo's checks once for every agent in the box, keyed on the working tree's contents, so two agents never run the same suite twice.

dev-ship

A deploy queue: agents enqueue pushed commits and one deploy ships them together.

hoststack-refresh-credentials

Re-seeds the box's API keys if one expires mid-session, without a redeploy.

Shipping and billing

Have the agent commit and git push: a push to the branch a service deploys from deploys it, exactly as a push from your laptop would. The in-box hoststack CLI is signed in as you, so hoststack services, hoststack logs and hoststack deploy trigger need no login.

A box is billed like the service it is: its size, plus the /workspace volume at €0.10/GB-month (€1/mo for the default 10 GB), plus any companions at their managed-database price. On your own machine there is no size price — see Your own machines. The coding agents themselves cost nothing extra; you bring your own agent subscription or API key.

Next steps

• Move your dev environmentBring your repo, swap docker-compose for in-box engines and restore data.
• Run a box on your own machineA desktop or home server you own, with no compute charge.
• MCP serverEvery HostStack tool the agents in a box can call.
• Managed databasesBacked-up Postgres, MySQL, MongoDB and Redis to link into a box.