Configuration

The manager is configured via alien-manager.toml. Generate a template:

alien serve --init

Place the file in the working directory, or specify a path:

alien serve --config /etc/alien/manager.toml

Configuration priority (lowest to highest): TOML defaults → TOML file values → environment variables → CLI flags.

Where a file is awkward to mount, as on Amazon ECS, put the file's contents in the ALIEN_MANAGER_CONFIG environment variable instead. It is read when no --config path is given.

Other environment variables:

ServerCopy Anchor Link

[server]
port = 8080
host = "0.0.0.0"
base-url = "https://manager.example.com"
releases-url = "https://releases.alien.dev"
deployment-interval-secs = 10
heartbeat-interval-secs = 60

Environment variable overrides: PORT, HOST, BASE_URL.

DatabaseCopy Anchor Link

[database]
path = "/var/lib/alien/alien-manager.db"
state-dir = "/var/lib/alien/state"
encryption-key = "your-64-char-hex-key"

Artifact RegistryCopy Anchor Link

By default, the manager starts an embedded container image registry and serves it at its own URL, so pull deployments (Kubernetes, the Operator) need no registry of their own. Images live in the manager's state directory.

To keep release images in a cloud registry instead, set default. Pull deployments still pull through the manager, which forwards to that registry. For push deployments on AWS, GCP, and Azure, the cloud pulls images directly, so configure a registry in that cloud:

ECR (AWS)Copy Anchor Link

[artifact-registry.aws]
service = "ecr"
repositoryPrefix = "alien-artifacts"
pullRoleArn = "arn:aws:iam::123456789:role/ecr-pull"
pushRoleArn = "arn:aws:iam::123456789:role/ecr-push"

GAR (GCP)Copy Anchor Link

[artifact-registry.gcp]
service = "gar"
repositoryName = "alien-artifacts"
pullServiceAccountEmail = "pull@project.iam.gserviceaccount.com"
pushServiceAccountEmail = "push@project.iam.gserviceaccount.com"

The manager gives each Alien project its own GAR repository, <repositoryName>-prj-<id> (or <repositoryName>-default), in the manager's GCP project and region, so a deployment's grant reaches only its project's images. Deleting a deployment removes its grant; the project's repository stays. Images pushed under the single <repositoryName> repository by older managers are not migrated, and the manager no longer serves them. The manager does not need that repository to exist.

The manager's identity needs these permissions on that GCP project: artifactregistry.repositories.create, .get, .list, .getIamPolicy, and .setIamPolicy. When the pull and push service accounts are set, the manager also grants them reader and writer on each repository it creates.

ACR (Azure)Copy Anchor Link

[artifact-registry.azure]
service = "acr"
registryName = "myregistry"
resourceGroupName = "rg-alien"

Local (explicit)Copy Anchor Link

Usually you don't need to set this — the embedded registry starts automatically. But if you want to control the URL or data directory:

[artifact-registry.default]
service = "local"
registryUrl = "localhost:5000"
dataDir = "/var/lib/alien/registry"

CommandsCopy Anchor Link

Backend storage for the commands protocol. The KV store holds command state; the storage backend holds large request/response payloads.

Default: local filesystem in {state-dir}/commands_kv and {state-dir}/commands_storage.

For push-mode deployments (Lambda, Cloud Run), use cloud-backed storage so runtimes can access presigned URLs.

DynamoDB + S3 (AWS)Copy Anchor Link

[commands]
kv = { service = "dynamodb", tableName = "alien-commands", region = "us-east-1" }
storage = { service = "s3", bucketName = "alien-command-storage" }

Firestore + GCS (GCP)Copy Anchor Link

[commands]
kv = { service = "firestore", projectId = "my-project", databaseId = "(default)", collectionName = "alien-commands" }
storage = { service = "gcs", bucketName = "alien-command-storage" }

Table Storage + Blob (Azure)Copy Anchor Link

[commands]
kv = { service = "tablestorage", resourceGroupName = "rg-alien", accountName = "alienstate", tableName = "aliencommands" }
storage = { service = "blob", accountName = "alienstate", containerName = "alien-commands" }

Redis (Kubernetes)Copy Anchor Link

[commands]
kv = { service = "redis", connectionUrl = "redis://redis:6379" }

ImpersonationCopy Anchor Link

Cross-account credential impersonation for push-mode deployments. Each platform entry provides a service account identity that the manager assumes when deploying to remote environments.

AWSCopy Anchor Link

[impersonation.aws]
service = "awsiam"
roleName = "alien-management"
roleArn = "arn:aws:iam::123456789:role/alien-management"

GCPCopy Anchor Link

[impersonation.gcp]
service = "gcpserviceaccount"
email = "alien-management@project.iam.gserviceaccount.com"
uniqueId = "123456789012345678"

AzureCopy Anchor Link

[impersonation.azure]
service = "azuremanagedidentity"
clientId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
resourceId = "/subscriptions/.../providers/Microsoft.ManagedIdentity/..."
principalId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

TelemetryCopy Anchor Link

[telemetry]
otlp-endpoint = "https://otel-collector.example.com:4318"

[telemetry.headers]
DD-API-KEY = "your-datadog-key"
Authorization = "Basic base64encoded"

Environment variable override: OTLP_ENDPOINT.

The manager collects OpenTelemetry data from deployed workers and forwards it to the configured endpoint. Use any OTLP-compatible backend — Grafana, Datadog, Honeycomb, Jaeger, etc.

Alien preserves captured application bodies and can normalize severity from common structured formats. See Observability → Structured log severity.

OperatorCopy Anchor Link

Charts the manager serves run this Operator image, pulled through the manager with the deployment's token, and Operators installed from them update themselves to it.

[operator]
image = "registry.example.com/alien-operator:v3.3.25"

Example: Minimal Production ConfigCopy Anchor Link

[server]
port = 8080
base-url = "https://manager.example.com"

[database]
path = "/var/lib/alien/alien-manager.db"
state-dir = "/var/lib/alien/state"
encryption-key = "your-64-char-hex-key"

[telemetry]
otlp-endpoint = "https://otel-collector.example.com:4318"

Example: AWS Push-ModeCopy Anchor Link

[server]
base-url = "https://manager.example.com"

[database]
path = "/var/lib/alien/alien-manager.db"
state-dir = "/var/lib/alien/state"
encryption-key = "your-64-char-hex-key"

[artifact-registry.aws]
service = "ecr"
repositoryPrefix = "alien-artifacts"
pushRoleArn = "arn:aws:iam::123456789:role/ecr-push"

[commands]
kv = { service = "dynamodb", tableName = "alien-commands", region = "us-east-1" }
storage = { service = "s3", bucketName = "alien-command-storage" }

[impersonation.aws]
service = "awsiam"
roleName = "alien-management"
roleArn = "arn:aws:iam::123456789:role/alien-management"

[telemetry]
otlp-endpoint = "https://otel-collector.example.com:4318"

Example: Local DevelopmentCopy Anchor Link

For local testing, the defaults are usually sufficient. Just run:

alien serve

This starts the manager on port 8080 with an embedded registry and a local SQLite database.