Skip to main content

Integration bundle

The console's Settings, API section generates an integration bundle: a config.toml, a one-line install command for the fleet agent, and ready-to-paste snippets for IDE agents. This page documents what the bundle contains so you can audit it, regenerate it by hand, or debug an agent that will not connect.

config.toml​

The bundle writes this file to ~/.constellation/config.toml:

# Constellation fleet agent - gateway-key
# Generated 2026-07-09T14:32:00.000Z

[constellation]
api_url = "https://api.constellation.space"
api_key = "<your API key>"
tenant = "acme-sat"
environment = "prod"
api_base = "https://api.constellation.space"
console_base = "https://sos.constellation.space/app/api/os"
routing = "direct"

[auth]
token = "<your API key>"

[endpoints]
topology = "https://api.constellation.space/topology"
predictions = "https://api.constellation.space/predictions"
telemetry = "https://api.constellation.space/telemetry"

[telemetry]
mode = "push"
interval_seconds = 30
measurements = ["link", "satellite", "ground_station", "weather", "telemetry"]
content_type = "application/json"
batch_max_records = 1000

Key facts encoded in the file:

  • The telemetry contract matches the Telemetry endpoint exactly: JSON array bodies, 1,000-record batch cap, the five canonical measurements, a 30 second push interval.
  • routing is direct in production use. The console_proxy routing option only works under local console development; against the real platform, agents call the API base directly.
  • tenant is informational. The platform derives your tenant from the key, never from this field or the hostname.

Keep the file mode 0600; it contains the key in plaintext.

Install command​

The console emits a single copy-paste block that installs the agent from the console origin and writes the config:

curl -fsSL "https://sos.constellation.space/app/integrations/install.sh" | sh -s -- \
  --script-url "https://sos.constellation.space/app/integrations/install.sh" \
  && mkdir -p "$HOME/.constellation" \
  && cat > "$HOME/.constellation/config.toml" <<'CONSTELLATION_CONFIG'
# ... the config.toml above ...
CONSTELLATION_CONFIG

When the bundle is generated without revealing the secret, the config contains the placeholder REPLACE_WITH_API_TOKEN; swap in the real key before starting the agent. The agent ships as the npm package @constellation/fleet-agent, and integrations conventionally read the key from the CONSTELLATION_API_TOKEN environment variable.

The Bearer versus x-api-key gap​

Be aware of one honest rough edge. The platform API authenticates exactly one way: the x-api-key header (Authentication). The generated config.toml carries the credential in two places, [constellation].api_key and [auth].token, and older fleet agent builds and third-party tooling reading the [auth] section have sent it as Authorization: Bearer <token>. The platform does not accept Bearer tokens, so those requests fail with 401 auth_failed, and repeated failures trip the auth lockout.

If a freshly installed agent gets 401 with a key that works in curl via x-api-key, check which header your agent version sends before rotating anything.

Also note: keys minted locally in the console browser (marked local origin in the bundle) are not registered with the platform and will return 401 until the platform team provisions them.

Staged connection test​

The console's "Test connection" runs a staged probe against the real API, and the same flow is the right shape for your own smoke tests:

StageRequestPass condition
1. ReachabilityGET /health200, status: ok, no failing checks.
2. Telemetry subsystemGET /health/telemetry200 and healthy body.
3. Topology subsystemGET /health/topology200 and healthy body.
4. Authenticated data planeGET /topology?freshness_seconds=900 with x-api-key200; parse tenant_key, count distinct node ids, find the newest observed_at.

Stage 4 interpretation mirrors the console:

  • 401: key rejected; verify the tenant x-api-key.
  • 503: tenant data plane unavailable, possibly a disabled tenant.
  • 200 with zero nodes: authenticated, but no telemetry in the last 15 minutes; start the fleet agent to begin ingest.
  • 200 with nodes: connected, telemetry flowing; report node count and newest sample time.

Stages 1 to 3 run without credentials, so the test degrades gracefully when no key is configured: it still proves reachability and subsystem health, and reports the authenticated stage as not tested rather than failed. A runnable four-language version is in Connection smoke test.