Local development

Local development runs your whole stack on your machine with alien dev, with a local stand-in for every cloud resource and no cloud account. Run it from the folder with alien.ts:

alien dev

alien dev builds the stack, releases it to a local manager (the Alien server that stores releases and rolls them out), and deploys it. The same deployment is the target for tests.

Start a sessionCopy Anchor Link

The command does this once, in order:

1. 1

   Start a local manager

   On localhost:9090 (--port), with state in .alien/ in your project.

2. 2

   Build

   Compiles every Worker, Container, and Daemon for the local platform.

3. 3

   Release and deploy

   Creates a release and deploys it as the deployment named default (--deployment-name).

4. 4

   Show status

   Prints resources and endpoint URLs, then keeps the deployment running until you press Ctrl+C.

alien dev does not watch files. After you change code or alien.ts, stop it and run it again.

Add --skip-build to reuse the previous build when only configuration changed; it fails if the local artifacts it needs are missing. To prebuild them:

alien build --platforms local --targets linux-x64,darwin-arm64
alien dev --skip-build

Workers and Daemons run as native processes, so include your host's target (darwin-arm64, linux-x64, linux-arm64, or windows-x64). Containers always use Linux images (linux-x64 or linux-arm64).

The session waits up to 300 seconds for the deployment to become ready. Set ALIEN_DEV_DEPLOYMENT_TIMEOUT_SECONDS (a positive integer) to wait longer on a slow first build.

When the wait expires, the manager may still be deploying. Check alien dev deployments ls before you retry.

You need Bun for TypeScript sources and Docker running. You don't need cloud credentials.

Local resourcesCopy Anchor Link

Each resource gets a local equivalent, and your code uses the same bindings:

Some resources have no local equivalent, such as Key. Test those in a cloud deployment. Per-platform support is in Platforms.

Work with the running deploymentCopy Anchor Link

Run these from a second terminal while the session runs. Each alien dev subcommand targets the local manager:

# Send a command to a handler
alien dev commands invoke --deployment local-dev/default --command search --params '{"prefix": "", "limit": 10}'

# Provide a deployer secret input, the way a customer's admin would
alien dev vault set deployer-secrets ocr-license-key --stdin

# Inspect the deployment
alien dev deployments ls

Pass environment variables when you start the session. Append :resource to limit one to a workload:

alien dev \
  --env ACME_API_URL=http://localhost:3000 \
  --secret-env OPENAI_API_KEY=OPENAI_API_KEY:processor

--secret takes a literal value, --secret-file reads it from a file, and --secret-env copies it from your shell's environment.

Simulate several customersCopy Anchor Link

Start only the local manager, then release once and deploy it under several names, one per simulated customer:

alien dev server

alien dev release
alien dev deploy --name customer-1
alien dev deploy --name customer-2

Each deployment has its own resources and data.

State and cleanupCopy Anchor Link

Restarting alien dev from the same folder keeps the deployment and its data in .alien/.

• One manager owns a .alien/ folder at a time, even on a different port. Stop the running session before starting another.
• For two sessions at once, use two project folders and two ports.
• Don't delete .alien/ to recover from a killed manager: the next one picks up its unfinished work when it starts.

If the previous startup or update failed, restarting alien dev retries the deployment once with the new build. Fix the cause first; the session doesn't retry a failing deployment in a loop.

Ctrl+C or SIGTERM finishes in-progress reconciliation, drains native Workers, and stops the session's Docker containers. Data and container metadata stay for the next session. A signal received during a build takes effect when the build finishes.

Storage triggers and storage notifications keep a cursor in .alien/. A restart replays nothing already delivered, and objects written while the session was stopped arrive once it's back.

A crash can still redeliver an event, so make handlers safe to run twice. Local triggers see the latest state of each object, not every intermediate overwrite.

To delete the local deployment and its resources:

alien dev destroy --name default

For scripts and coding agents, --status-file .alien/dev-status.json writes the session's state, resources, and URLs as JSON, so nothing has to parse terminal output.

NextCopy Anchor Link

• Testing: run the same local deployment from your test suite
• Releases: ship the stack to real deployments
• CLI reference