Building apps

Let an AI build & deploy

This is the headline use case. Stand Astrodock up once, then point a coding agent — like Claude Code — at it and let the agent build a small app and launch it on the open internet, end to end. You hand over a token and a contract; the agent does the loop.

Before you start

You should have Astrodock installed and running. If you've never deployed an app here by hand, do Deploy your first app first — the agent runs the exact same loop, so it helps to have seen it once.

How it works

Astrodock gives an agent everything it needs to ship without you in the loop for each step:

Give the agent the token and point it at AGENTS.md, and it has a precise, drivable path from empty folder to a live URL.

Step 1 — Mint a token for the agent

In the dashboard, open Tokens → New token and give it a name (e.g. "claude agent"). The value is shown once — copy it. You can optionally scope the token to specific app slugs so the agent can only touch those apps.

Scope it down for one task

If you want the agent to work on just one app, restrict the token to that app's slug. A fresh, unscoped token is fine for "build me something new" since the agent picks the slug as it scaffolds.

Step 2 — Give the agent its two env vars

The CLI reads exactly two environment variables. Set them in the agent's shell:

export ASTRODOCK_URL="https://admin.your-domain"   # your admin host
export ASTRODOCK_TOKEN="tk_paste-the-token-here"   # the scoped token

Locally that's http://admin.localhost. These are the same two variables you used in Deploy your first app — nothing agent-specific about them.

Step 3 — Point the agent at the contract

The build/deploy contract lives in AGENTS.md at the repo root. It tells the agent the app layout (app/ frontend + server/ Express), the hard rules (bind ASTRODOCK_PORT, routes under /api, add GET /health), the app.json manifest, the reserved ASTRODOCK_* env model, and the deploy lifecycle. Tell the agent to read it first.

Per-app AGENTS.md and CLAUDE.md

The starter template emits its own AGENTS.md + CLAUDE.md into every new app. So once the agent scaffolds from the starter, the repo it's working in already carries the conventions — an agent opened in that folder knows the rules without you repeating them.

The loop the agent runs

With the token, the env vars, and the contract, the agent runs this loop:

  1. Scaffold from the starter

    Copy examples/starter-app into a new repo and keep the app/ + server/ layout (the runner auto-detects it).

  2. Write app.json

    Set the slug, subdomain, runtime, and the resource modes (auth / database / storage each internal / external / none). Declare env-var names only — never secret values.

  3. astrodock apply

    Creates the app, connects the repo, and provisions resources and routing in one pass.

  4. astrodock set-secret for required secrets

    If app.json declares required secrets, or a resource is in external mode, set those values. The CLI tells the agent exactly what's missing.

  5. astrodock deploy:watch

    Triggers a deploy and streams the log until success or failure. This is how the agent confirms the launch — it can read the terminal status and react.

  6. Confirm success

    Done when deploy:watch ends in success and https://<subdomain>.<base-domain> serves the app.

An example prompt

Open your agent in the Astrodock repo (with the two env vars set) and give it something like:

Read AGENTS.md, then build a small "link shortener" app and launch it on this
Astrodock platform.

- Scaffold from examples/starter-app into a new folder.
- Use platform auth, an internal database, and no object storage.
- Write app.json (slug "shortener", subdomain "go").
- Run: astrodock apply, set any required secrets, then astrodock deploy:watch.
- Stop when deploy:watch reports success and tell me the live URL.

The agent reads the contract, scaffolds, writes the manifest, runs the CLI, watches the deploy log, and reports back the live URL — without you driving each command.

What the agent can — and can't — do

The token is the boundary. With a scoped API token, an agent can:

It cannot:

A deployed app runs real code

By design, the platform builds and runs whatever the agent commits — its dependencies, its buildCommand, and its runtime. That's the whole point, and it's also why you should only let agents work against repos and prompts you trust. See the Security page for the full model.

After a successful launch

If the app uses platform login (auth.mode = platform), the agent has shipped it but can't create the people who log in. You finish in the dashboard: create a user and grant them access to the app's slug — see Manage users & access.

Next steps