Step-by-step quickstart

Start from the published SDK packages. Version 0.1.0 is immutable; use it for this quickstart and bump versions only when you are intentionally testing a new release.

mkdir -p tmp/astraform-quickstart
cd tmp/astraform-quickstart
python3 -m venv .venv
. .venv/bin/activate
pip install 'astraform-remote-domain-author-kit[fastapi]==0.1.0' \
  astraform-remote-domain-conformance==0.1.0

Rename acme_remote_domain and the package metadata once you stop using the starter name. Do not leave tutorial names in production code like a hobby project.

The author kit ships the FastAPI starter as package data. Copy it from the installed wheel instead of reaching back into the monorepo.

python - <<'PY'
from importlib.resources import as_file, files
import shutil

source = files("astraform.remote_domain.author_kit").joinpath("templates/fastapi-minimal")
with as_file(source) as template:
    shutil.copytree(template, "acme-remote-domain", dirs_exist_ok=True)
PY

cd acme-remote-domain
pip install -e '.[test]'

# edit:
# src/acme_remote_domain/service.py
# src/acme_remote_domain/main.py

Your job is not to bypass the protocol. Your job is to implement your domain semantics inside the service object methods: manifest, prepare, execute_work, status, inspection, and shutdown.

uvicorn acme_remote_domain.main:app --host 0.0.0.0 --port 8092

curl http://localhost:8092/actuator/health
curl http://localhost:8092/api/remote-domain/v1/manifest

If your manifest is not truthful here, stop. Do not keep building on top of a lie and hope the host will save you later.

This is the minimum bar for “we built a valid remote domain” instead of “it worked once on one laptop.”

remote-domain-conformance \
  --app acme_remote_domain.main:app \
  --domain-id acme-remote

You can also point the harness at a running URL with --base-url http://localhost:8092.

The registration model is configuration-driven. These are the actual property names used by the host.

simulation.remote-domains.domains.acme-remote.base-url=http://localhost:8092
simulation.remote-domains.domains.acme-remote.manifest-path=/api/remote-domain/v1/manifest
simulation.remote-domains.domains.acme-remote.timeout-ms=5000
simulation.remote-domains.domains.acme-remote.enabled=true

If you are running the host locally, keep the domain ID consistent across the manifest, the conformance run, and the host registration. Inconsistency here is not flexibility. It is sloppiness.

curl http://localhost:8082/internal/simulation-domains

# inspect that your domain shows:
# - enabled=true
# - protocolCompatible=true
# - manifestFetched=true

Discovery is the first real host-level proof. If the host cannot fetch your manifest cleanly, you are not integrated yet.