Local Development

Run your entire stack locally with one command.

Starting a Dev SessionCopy Anchor Link

alien dev

This is the all-in-one local workflow. It starts a local server, builds your app with development settings, and deploys it.

For optimized builds, build the local artifacts first and reuse them:

alien build --platforms local --targets linux-x64
alien dev --skip-build

Choose targets for the resources in your stack: linux-x64 or linux-arm64 for Linux containers, plus darwin-arm64 for native Workers and Daemons on Apple Silicon, or windows-x64 for native Windows workloads. Pass multiple targets as a comma-separated list. --skip-build validates that the required local artifacts exist.

Every cloud resource gets a local equivalent:

No cloud credentials needed. No accounts. Docker is required only for builds and Container resources.

Restarting alien dev reuses the deployment and its data in .alien. Local setup and permission changes are reconciled in place. If a desired Container was removed from Docker, Alien recreates it without changing your application configuration, including when startup resumes from a saved health-check wait. Stopped desired containers also re-enter startup; paused containers and running workloads that fail health checks retain normal health-failure handling.

Each .alien state directory has one manager owner. Stop its current manager before starting another session, even on a different port. For simultaneous sessions, use separate project directories and different ports. The ownership lock releases when the manager exits; leave the lock file in place.

To deliberately delete a local deployment and its resources, run:

alien dev destroy --name default

Use the deployment’s ordinary name for cleanup if you selected a different deployment. Cleanup targets the local-dev group and refuses ambiguous matches.

Older clients could create a local deployment in another group. The updated CLI refuses to create a duplicate or guess which deployment to adopt. Stop the local manager, then select the existing deployment explicitly with alien dev --deployment-name dep_... or alien dev --deployment-name <group>/<name>. This moves that deployment to local-dev while preserving its ID, resource state, and data. A conflicting name in local-dev fails the migration. Later launches use its ordinary name.

Server-Only ModeCopy Anchor Link

If you want just the local server without the full build-deploy-watch cycle:

alien dev server

For a supervisor that needs a readiness file:

alien dev --status-file .alien/dev-status.json server

Then drive it manually with explicit commands:

alien dev release
alien dev deploy --name preview
alien dev deployments ls

This is useful when you want more control over the build-release-deploy cycle, or when integrating with other tools.

Deployment Readiness and RecoveryCopy Anchor Link

alien dev waits up to 300 seconds for the deployment to become ready. Increase this budget for slow first builds or image pulls:

ALIEN_DEV_DEPLOYMENT_TIMEOUT_SECONDS=600 alien dev

The value must be a positive integer. When this wait expires, the manager may still be deploying resources. Inspect the deployment with alien dev deployments ls before retrying.

Restarting a full alien dev session requests one retry of its selected deployment if the previous startup, update, or refresh failed. Failed local startup receives the newly built release while retaining its failed phase, so retry resumes or reconciles existing resource state. Fix the reported cause before restarting; a session does not repeatedly retry a failing deployment. Deletion failures require explicit cleanup.

Local Worker and Daemon releases use the native archive for your host OS and architecture. Container releases use Linux images. A prebuilt release must include the appropriate archives for each resource.

After a Worker restarts, local storage triggers replay existing committed objects and retry failed handlers. Make handlers safe to repeat. Filesystem reconciliation observes the latest object state; it does not preserve every intermediate overwrite or a create-and-delete that occurs between scans.

Docker containers use unless-stopped, which preserves a manual stop across Docker daemon restarts. While a session is running, Alien recreates a stopped desired container to restore its deployment. Deleting a deployment can delete its local resources and storage.

Stopping and RestartingCopy Anchor Link

Stop alien dev or alien dev server with Ctrl+C or SIGTERM. It finishes accepted reconciliation, drains native Workers, and stops the exact Docker containers tracked by its local deployments before exiting. Container metadata and persistent data remain for the next session. Stopped containers do not restart with Docker's unless-stopped policy; their saved Docker environment remains inspectable locally until the containers are replaced or deleted.

A SIGTERM received during a build is handled when startup reaches the watch phase; it does not immediately cancel compilation. Each server owns its state directory; a second server using the same directory fails even if it chooses a different port.

Restart from the same project directory to retain deployment identity and local data. If the previous manager was killed, the replacement recovers abandoned Local push execution claims as soon as it acquires exclusive ownership of .alien. Scheduled retry delays still apply, and claims held by independent pull operators remain intact. Do not delete .alien to clear a stale execution claim.

Agent-FriendlyCopy Anchor Link

For AI agents and automated tooling that need to read state programmatically:

alien dev --status-file .alien/dev-status.json

The status file is a JSON document that updates as the dev session progresses — no terminal output parsing required. Agents can poll this file to know when resources are ready, get endpoint URLs, and monitor health.