Getting started

Install an issued evaluation package and run your first governed workflow through the CLI. No AOS console is required.

Scope: 0.2.0-rc5 local evaluation on macOS or Linux with a POSIX shell. The example runs on your computer, uses disposable development identity and SQLite, and changes only an in-memory reference counter. It is not a production installation and does not restart a real service.

Documentation · Downloads and access · Product questions

1. Obtain your package

Check Downloads and access first. Public self-service package delivery is not open yet. Continue only after the product team has supplied a release package and its verification instructions.

For this candidate you need the file aos_core-0.2.0rc5-py3-none-any.whl. Do not assume a similarly named package from an arbitrary package index is the official release.

Verify the package against the release team’s authenticated checksum or signed release manifest before installation. A checksum downloaded from the same untrusted source as a file does not establish who supplied it.

# macOS
shasum -a 256 aos_core-0.2.0rc5-py3-none-any.whl

# Linux
sha256sum aos_core-0.2.0rc5-py3-none-any.whl

Compare the output with the verified release manifest. Stop if it differs.

2. Install in an isolated environment

You need Python 3.11 or newer, the issued wheel and internet access to install its dependencies. This is a connected installation, not an offline bundle.

In a new working directory, place the wheel beside you and run:

python3 --version
python3 -m venv .venv
. .venv/bin/activate
python -m pip install ./aos_core-0.2.0rc5-py3-none-any.whl
aos product --help

The installed package supplies aos, aos-runtime and aos-evaluate. The CLI is part of the same product package, not a separate paid interface.

3. Run the reference workflow

aos-evaluate --cli --output ./first-run --port 0

The evaluator starts a local control plane, runtime worker and reference HTTP service. It registers and approves the reference capability, executes an allowed action, checks a denied action, and simulates a lost response. It then writes evidence and stops the local services.

Use a new output directory for every run. Existing evidence is preserved.

python -m json.tool first-run/evaluation.json

Look for these fields:

{
  "status": "passed",
  "interface": "cli",
  "cli_invocation_exit_codes": [0, 3, 4],
  "provider_calls": 2,
  "ga_ready": false
}

This is an excerpt, not the full report. There should be two provider effects: the successful action and the action with a deliberately lost response. The denied request must not add a provider effect. ga_ready: false is expected because local evaluation does not qualify a production release.

4. Keep the local API running

Run a second evaluation in a fresh directory:

aos-evaluate --cli --output ./interactive-run --port 8765 --serve

Leave that terminal running. Open a second terminal in the same working directory and run:

. .venv/bin/activate
export AOS_URL='http://127.0.0.1:8765'
export AOS_TENANT_ID='free-evaluation'
export AOS_TOKEN_FILE="$PWD/interactive-run/console-token.txt"

aos product account status
aos product capability list
aos product runtime nodes
aos product runtime workloads --status unknown
aos product --output ./audit-review.json audit

The tenant name free-evaluation and any Free labels are internal fixtures in this candidate. They do not represent a publicly available free plan. The token file is used by the CLI despite its filename; do not paste its contents into commands, support forms or screenshots.

If port 8765 is busy, choose another port and use the printed URL for AOS_URL. The local token expires after eight hours. Stop the running evaluator with Ctrl-C when finished; your evidence files remain on disk.

The final reference policy denies additional actions. This is intentional. Inspect the recorded outcomes rather than repeatedly invoking the sample.

5. Inspect the evidence

Your additional audit-review.json is a CLI response envelope. Its data field contains the audit export as JSONL text. The evidence directory also contains a local database, tokens and keys; do not upload the whole directory to a public issue or share it as a sample package.

CLI exit codes

Troubleshooting

Command not found: reactivate .venv in the terminal where you run the command. Use python -m pip show aos-core to confirm the installed package.

Existing evaluation directory: use a new output path; do not overwrite previous evidence to repeat a run.

Connection refused: --serve must still be running, and AOS_URL must match the printed address.

Authentication rejected: check the tenant and token-file path. Start a fresh evaluation after the eight-hour token expires.

Audit output already exists: choose a new filename. CLI exports refuse to overwrite existing files.

Unknown outcome: inspect the runtime and provider state. Do not assume a timeout makes a repeated action safe.

Next: a real installation

A production installation requires its own supported release, access entitlement, PostgreSQL, external OIDC identity, HTTPS and deployment-specific policies and runtime configuration. Do not copy this evaluation’s identity token or SQLite database into production.

For an existing installation, obtain its HTTPS server origin, tenant ID and current token file from your administrator. Set AOS_URL, AOS_TENANT_ID and AOS_TOKEN_FILE to those values, then start with the read-only commands above.

Use aos product capability --help to inspect the registration, review and invocation commands. Real capability approval requires review of the exact contract and policy digests. Connect a non-production tool first and validate both permitted and denied actions before expanding access.

See Documentation for the architecture and Downloads and access for delivery status.