Skip to main content
Ambient Systems
Sign in
Request validation

Agent setup for Ambient

Hand this file to your own coding agent. It has two paths: open source (ambient-core) or commercial (Ambient org access through the marketing site).

One-line prompt for your agent: Read https://www.ambientsystems.ai/docs/agent-setup.md and set up Ambient for me.

Path A — Open source (ambient-core)​

Use this when you only need contracts, catalog semantics, and the example pipeline in your repository.

  1. Python — Use a supported 3.11+ interpreter in a virtual environment.
  2. Install and pin ambient-core — From PyPI or git, install the release tag v0.4.0 (not floating main unless you own the fork):
    • pip install "ambient-core @ git+https://github.com/Ambient-Team/ambient-core.git@v0.4.0"
    • Or clone, checkout v0.4.0, and pip install -e ".[pipeline]" when you need pipeline extras.
  3. Validate contracts — Run the package’s contract validation entry points (validate-contracts / documented CLI in ambient-core USAGE.md).
  4. Example pipeline — Copy sample CSVs per examples/pipeline/README.md, run the notebook or smoke script shipped at that tag.
  5. Tests — From the ambient-core checkout at v0.4.0, run its test suite (pytest as documented upstream). Fix only your integration layer if tests fail in your consumer repo.
  6. Stay pinned — Record v0.4.0 in your dependency lockfile or submodule. Bump only after you read the release notes for a newer tag.

No commercial login is required for Path A.

Path B — Commercial (Command Centre org)​

Use this when the customer has an Ambient subscription and needs the hosted Command Centre, not just the open-source libraries.

  1. Human sign-in — An org member signs in at https://www.ambientsystems.ai/login with the email Wix Members recognizes for that org. This marketing site is the only supported sign-up, verification, and password UI.
  2. What the agent receives from the customer — After sign-in, the operator (not the agent) may share:
    • Confirmation that the member is approved for org access (pending accounts cannot use operator routes).
    • Which hosting option applies: managed (one Ambient bill; Ambient pays the underlying cloud) or self-managed (customer pays the app and their own cloud). No prices in this doc — see Pricing.
    • The ambient-core pin their deployment uses (currently v0.4.0 on the public docs train unless their contract names another tag).
  3. What the agent does not have today
    • Planned: A public machine API for agents to provision tenants without a signed-in human. Agents must not invent REST routes or API keys that are not documented on https://www.ambientsystems.ai/docs/.
    • Planned: Self-serve download of proprietary platform source; access remains invitation-based through Ambient.
  4. Where to read product behavior — Public operator documentation lives at https://www.ambientsystems.ai/docs/ (Start Here → Operator). Integrator formulas and catalog definitions remain under open-source sync from ambient-core.
  5. Metering (when live) — Hosted workspaces record usage through the marketing-site BFF (/api/usage/meter) with the member Bearer token. Planned for full automation in consumer agents; today only documented platform builds call it.

If the customer is not approved or has no org, stop and ask them to complete sign-in and validation first.

Verify your work​

  • Path A: contract validation passes, example pipeline runs, ambient-core tests green at v0.4.0.
  • Path B: customer can sign in on the marketing site, sees Account (profile), and you have their written hosting choice and core pin—without storing their password in your agent logs.

Canonical copy​

This Markdown is generated from content/agent-setup.md in the ambientsystems.ai repository so a future copy can ship inside ambient-core without drifting. Edit that file only; wiki pages are produced by scripts/sync-agent-setup-to-wiki.mjs.