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 move beyond the starter. Keep tutorial names out of production domain code.

The author kit ships the FastAPI starter as package data. Copy it from the installed wheel instead of relying on a local source tree.

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

Verify the manifest is truthful before continuing. The host depends on it for compatibility, discovery, and supportability.

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. Inconsistent IDs create avoidable integration failures.

curl http://localhost:8084/api/dashboard/runtime/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.