Deployment

0.2.0-rc14 is an official release candidate, not general availability. The local Environment walkthrough is ready for evaluation. A production installation needs deployment-specific identity, infrastructure, security and recovery qualification.

Documentation · Downloads · Integrations · Identity and governance · Security

Choose where AOS runs

WordPress hosts this website, documentation and protected early-access download flow. Your AOS control plane and runtimes run in your infrastructure. Downloading the package does not create a hosted AOS service or a cloud account.

The wheel includes aos, aos-runtime, aos-evaluate and aos-workspace. The local evaluator needs Python only; the optional workspace workflow additionally needs Docker and Ollama. Shared deployments use external OIDC, PostgreSQL and HTTPS. Kubernetes/Helm packaging exists; image registry credentials and a deployment-qualified chart/image bundle are separate from the public wheel delivery.

Start with one non-production control plane and one connector runtime. Add HA only after the simple deployment passes acceptance. Cross-region recovery is promoted standby with operator fencing of the old database writer, not two writable database primaries.

Shared installation recipe

The following is a configuration recipe for a Linux host, not a claim of a qualified hosted service. Install the issued wheel in a dedicated virtual environment and run under a dedicated OS account. Create a private persistent directory for AOS state and mount secrets from your secret manager. Keep the package’s previous virtual environment for rollback.

Prepare a PostgreSQL database, least-privilege account, encrypted backups and restore procedure. Put its SQLAlchemy connection URL in /run/secrets/aos-database-url, for example using the postgresql+psycopg driver. Keep that file private; do not copy a real URL into shell history or website support.

Replace all example hosts, paths and claims. Configure OIDC as described in Identity and governance, then set the control-plane environment:

export AOS_DEPLOYMENT_MODE='production'
export AOS_DEPLOYMENT_PROFILE='shared'
export AOS_DATA_DIR='/var/lib/aos'
export AOS_DATABASE_URL_FILE='/run/secrets/aos-database-url'
export AOS_RUNTIME_EXECUTION_PROFILE='governed'
export AOS_ALLOW_MOCK_EXECUTION='false'
export AOS_COMMERCIAL_PROVIDER='disabled'
export AOS_PRODUCT_LICENSE_MODE='free'
export AOS_CUSTOMER_ACCESS_MODE='legacy'
export AOS_SELF_SERVICE_ENABLED='true'
export AOS_CONNECTOR_ALLOWED_HOSTS='["tools.example.com","api.openai.com"]'
export AOS_CONNECTOR_ALLOW_PRIVATE_NETWORKS='false'
export AOS_EGRESS_MODE='declared_only'
export AOS_EGRESS_ALLOWED_HOSTS='["identity.example.com","tools.example.com","api.openai.com"]'
aos db upgrade
aos db current
uvicorn aos.api.app:app --host 127.0.0.1 --port 8000 --workers 1

free and legacy here select the current free-access enrollment model, not anonymous authentication or a billing bypass. All privileged requests still need identity and tenant authorization. The current public offer has no payment provider or automatic conversion. A future paid deployment requires a separately configured entitlement/license and published terms.

Add secret-manager hosts to the egress configuration when used. Infrastructure egress rules must cover SDK secret retrieval and identity services too; connector allow-lists are not a system firewall. Keep metadata endpoints blocked unless a separately reviewed workload identity design requires them. Do not copy the local workspace’s HMAC secret or SQLite store. Production mode rejects development HMAC identity, mock execution and a non-PostgreSQL database.

Place the loopback service behind an HTTPS reverse proxy. Preserve Authorization, tenant and request identifiers, set sensible request/body/time limits and route only intended hosts. Run it under a service supervisor with the same protected configuration and working directory. Do not expose port 8000 or the local workspace portal directly. The production API deliberately disables the interactive /docs and /openapi.json endpoints; the versioned contract export is available through aos contracts export DIRECTORY for administrator review.

Enroll a runtime

Provision a short-lived IdP service-account token with runtime_publisher and matching runtime_id/node_id claims. Save it as /run/secrets/aos-runtime-token. On the worker, install the same release and configure:

export AOS_RUNTIME_CONTROL_URL='https://aos.example.com'
export AOS_RUNTIME_TOKEN_FILE='/run/secrets/aos-runtime-token'
export AOS_RUNTIME_TENANT_ID='engineering'
export AOS_RUNTIME_RUNTIME_ID='engineering-connectors'
export AOS_RUNTIME_NODE_ID='connector-01'
export AOS_RUNTIME_PROVIDERS='["connector"]'
export AOS_RUNTIME_EGRESS_MODE='declared_only'
export AOS_RUNTIME_EGRESS_ALLOWED_HOSTS='["aos.example.com","tools.example.com","api.openai.com"]'
aos-runtime doctor
aos-runtime run

Supervise the runtime process and arrange token renewal/restart through your identity tooling. Mount the provider secret references on every component that resolves them; the control-plane probe and worker execution may run on different hosts. Set network controls in your infrastructure as well as AOS configuration.

From an operator terminal, configure the product CLI’s server, tenant and token file. Bootstrap that tenant if not yet enrolled:

aos product account create --organization 'Engineering' --name 'Engineering workspace'
aos product account status
aos product runtime nodes

Check a ready node with the expected runtime and identity. Then follow Integrations to register a read-only test service, approve its exact contract and test allowed/denied operations. The UI at your installation’s /console/ uses the same backend and identities. Do not use one shared token for all human roles.

Release validation and rollout

rc12 adds database migration 20261110_0031 for action reviews. Pause gateway writes, back up the database, apply the migration and test separate requester/reviewer identities before resuming. Contracts requiring action approval now reject direct invocation without a valid review. Read Action approvals and Release notes before upgrading.

Keep a release record with the version, immutable wheel/image/chart hashes, configuration revision, database revision and acceptance results. Verify the downloaded wheel’s checksum against Downloads. A signed release checksum, when distributed, must be verified against an independently trusted signer; the ordinary website ZIP’s checksum alone is not that independent signature.

For each deployment, validate authentication and tenant isolation, secret rotation, capability drift, runtime isolation, policy preflight and separate approval, unknown-outcome reconciliation, audit signing/export verification, retention, monitoring, sustained workload behavior and restore from backup. Fixture tests and a local CPU workflow do not establish cloud/GPU performance, live vendor compatibility, resilience or security certification.

Before an upgrade, stop accepting new consequential work, reconcile in-flight/unknown operations, retain independent evidence, back up state and test migrations against a restored copy. Install the new release alongside the old environment, apply reviewed migrations, restart controlled services and rerun acceptance. Expand traffic only after checks pass.

Rollback and incident handling

Rolling back to rc11 removes the new action-approval enforcement. Keep writes disabled until a compatible server is restored. Preserve the replay-guard table and its payload-free tombstones; restoring an older database or pruning guards can admit an old action again. An already deleted rc11 replay record cannot be retroactively protected.

Retain the previous package and configuration. Application rollback is appropriate only when the database remains compatible; restoring a backup can lose newer records and requires an explicit recovery decision. A policy rollback is separate from application rollback and does not reverse external effects.

If authority or credentials are compromised, block new work, revoke affected contracts, rotate credentials, preserve evidence and reconcile actual provider state. Logs, AOS records and an agent’s narrative can disagree; keep that uncertainty visible. Recovery requires a validated state, not simply replaying timed-out writes.

Use the contact form for release or integration questions with redacted errors and version/OS details. No production support SLA or live cloud account qualification is implied by the early-access package.