Connect to GraphOS Agent Services

Start the runtime from the onboarding kit and confirm enforcement

PREVIEW

GraphOS Agent Services is in private preview. You need an Apollo team member to help you onboard. Use this documentation for reference only.

This tutorial is for anyone who calls the graph. Creating the sandbox organization, connecting a service, and writing an access rule requires an Org Admin role.

You unzip the onboarding kit, add your personal API key, start the local runtime, and confirm enforcement.

If you already unzipped the kit and set APOLLO_POLICY_KEY, skip to Start the runtime.

Prerequisites

You need these:

Docker Desktop or Colima, with a memory limit of at least 6 GiB
Python 3
Git and curl
Claude Code or Claude Desktop

Your Apollo contact provides the onboarding kit. Use the 01-policy/policy_rules.yaml your Org Admin wrote.

Unzip the onboarding kit

Unzip the kit your Apollo contact sent into a new directory. Don't unzip over an older kit.
In a terminal, go to that directory.

The kit is self-contained. The only value you fill in by hand is your personal API key.

./onboard.sh applies 01-policy/policy_rules.yaml from this kit. Confirm the file matches the one your Org Admin wrote.

Add your personal API key

Copy the example environment file:
terminal
cp .env.example .env
In Studio, select your avatar on the top right, then Personal settings → API Keys.
Create a new personal API key. This key starts with user:.
Set APOLLO_POLICY_KEY in .env to that value.

If the service you connect uses a credential (GITHUB_TOKEN, SLACK_TOKEN, and similar), set that value in .env too. Leave unused connector credentials as REPLACE_ME.

Start the runtime

From the kit directory, run:

terminal

./onboard.sh

That command runs these steps in order. Each step is idempotent, so if one step fails partway through, re-running is safe.

Step	What it does
`prereqs`	Checks Docker, ports, and tool versions
`bootstrap`	Finds your org and graph, mints a graph API key, and fills the rest of `.env`
`policy`	Applies `01-policy/policy_rules.yaml`
`artifact-ref`	Looks up the graph artifact the runtime should serve
`up`	Boots the local runtime and smoke-tests it
`connect`	Registers the MCP server with Claude Code and Claude Desktop

If bootstrap finds more than one GraphOS Agent Services graph, bootstrap asks you to choose. To pin a graph yourself, set APOLLO_GRAPH_REF to <graph-id>@current before you re-run.

Wait until the terminal prints a -- Ready -- block like this:

terminal

-- Ready --
 Sandbox:   http://localhost:4101/graphql
 Grafana:   http://localhost:3000/d/constellation-runtime
 MCP:       http://localhost:4100/mcp
 Inspector: http://localhost:6274/

 Next: ./onboard.sh connect
------------

note

The runtime refuses to boot until the graph artifact includes a compiled policy bundle. The policy step of ./onboard.sh triggers a launch that bakes the bundle in. If up fails with a missing policy-bundle, run ./onboard.sh debug-artifact and wait until the command reports ok: policy-bundle present. Then run ./onboard.sh artifact-ref and ./onboard.sh up again. Don't edit APOLLO_GRAPH_ARTIFACT_REFERENCE by hand.

Connect Claude

./onboard.sh already runs connect when the runtime is ready. If you started the runtime on its own, run:

terminal

./onboard.sh connect

Then:

Restart Claude Desktop so Claude Desktop picks up the MCP server.
In Claude Code or Claude Desktop, send a first question about the connected service. The first tool call opens a browser for sign-in. That's expected.
Sign in with the same GitHub identity or username and password you used for the sandbox org, not company SSO.

tip

For a dedicated Claude Code workspace that always reaches for this runtime, run ./onboard.sh agent-skills, then cd constellation-agent && claude.

If Claude Desktop wasn't installed when you ran connect, add this to Claude → Settings → Developer → Edit Config:

JSON

1"graphos-agent-services": {
2  "command": "npx",
3  "args": ["mcp-remote", "http://localhost:4100/mcp"]
4}

Make a call and see enforcement

Ask in natural language. Don't mention GraphOS Agent Services. The MCP server decides when to query the graph.

For The Cat API, start with data the policy allows:

Show me a few cat breeds and where they're from.
Find breeds that are good with kids.

Then ask for a field the policy denies:

Show me random cat pictures.
What's the full description of the Siamese breed?

You should get breed lists back, and see image URLs and descriptions blocked as requestable. If you added the registry service, follow up with: "Request access to the image URLs so you can show me pictures."

You can also open Apollo Sandbox at http://localhost:4101/graphql and run the same operations directly.

That's a working local instance: a connected service, an applied access rule, a running runtime, and an agent call that hits enforcement.

Troubleshooting

Run these from the kit directory and share the output with your Apollo contact:

Symptom	Command
A prerequisite check fails	`./onboard.sh prereqs`
Browser sign-in fails or returns `access_denied`	`./onboard.sh debug-oauth`
Runtime serves an old schema or policy	`./onboard.sh debug-artifact`
`up` fails with `invalid peer certificate: UnknownIssuer`	`./onboard.sh setup-tls`, then `./onboard.sh up`
A container keeps restarting	`./onboard.sh support-bundle`

Corporate networks that intercept TLS (Zscaler, Netskope, Palo Alto) need ./onboard.sh setup-tls before up. The runtime trusts the container's certificate store, not your Mac keychain.

For sign-in failures after debug-oauth reports a clean config, clear the browser session for apollographql.com and auth.apollographql.com, delete ~/.mcp-auth, and reconnect.

To shut the runtime down when the session ends:

terminal

./onboard.sh teardown

Give FeedbackFeedback