This is preview documentation. The official release is not yet available.
Prepare
Install Docker Engine or Docker Desktop, Compose v2 and OpenSSL. Checkdocker info and docker compose version. Provide your own model credentials. Reserve persistent disk space for database and work files; CPU and memory depend on concurrency and tool load.
Download agentscope-service-VERSION-compose.tar.gz and SHA256SUMS from the selected Release. Compare the archive’s SHA-256 with its manifest entry using sha256sum on Linux or shasum -a 256 on macOS. Use the Release’s VERSION and REGISTRY/NAMESPACE below; the registry path has no https:// prefix.
1. Start
600 .env with database, JWT, internal-token, Vault and initial administrator secrets. Running the script again preserves the file rather than changing versions or resetting passwords.
2. Sign in
http://localhost:18080. Sign in with admin and AISTIO_BOOTSTRAP_PASSWORD from .env, then change the password in Profile. Bootstrap creates an administrator only in an empty user database; restarts do not reset accounts.
3. Configure execution
For a trusted local evaluation, edit.env:
docker compose up -d --wait --wait-timeout 600. Local tools execute inside Dataplane, without automatically mounting host files. Follow quickstart to create a Managed Agent.
Alternatively, connect an existing Coding Agent through Hosted execution. Keep Local disabled and configure an appropriate Environment when tool isolation is needed.
Network surfaces
A same-host reverse proxy can use
127.0.0.1:18080. In another container, localhost refers to that proxy container; configure a shared network or reachable host address. Expose Gateway to users and keep internal components and PostgreSQL private.
Enable remote access
Use this section when accessing your local service from another device or testing public OAuth/Channel callbacks. Prepare a domain and TLS certificate, then proxy HTTPS to Gateway. SetBUILDER_OAUTH_PUBLIC_URL=https://agentscope.example.com in .env. Adjust BIND_ADDRESS and GATEWAY_PORT if needed, then recreate containers.
The proxy must forward SSE promptly, avoid event-stream caching and allow sufficiently long read timeouts. Verify login, long replies, reconnection and OAuth/Channel callbacks, not just the home page.
Persist data
Named volumes store PostgreSQL, shared Workspaces and Artifacts. Locate project volumes withdocker volume ls and back them up according to your storage policy. Preserve the Vault master key from .env with encrypted data.
For host directories, configure explicit mounts and access for container user 65532:65532. An Agent instruction containing a local path does not make it readable inside the container. File access must match the selected Environment.
Change configuration or version
After editing.env:
init-env.sh preserves existing configuration, so edit SERVICE_VERSION to change versions. Coordinate secret changes across consumers; Vault master keys cannot be casually replaced.
Complete Compose runs standalone HTTP. ASDP-dependent SDKs need the corresponding External integration deployment. See production installation for production deployments and rehearse recovery before upgrading.
Stop, resume and diagnose
docker compose down stops services while preserving volumes. Repeat the startup command to resume. Do not add -v for ordinary shutdown; it deletes data volumes.
For startup failure, inspect docker compose ps -a and docker compose logs --tail=100 for image, database and component errors. Resolve a port conflict by changing GATEWAY_PORT and the corresponding BUILDER_OAUTH_PUBLIC_URL in .env, then recreate containers.
Next: Quickstart · Production installation.