Convex
Connect
Connect Convex from the terminal. Pass --help for the flags Convex accepts, plus --no-browser for headless environments.
polylane cloud connect --provider convexA team access token from Team Settings → Access Tokens in the Convex dashboard.
Connect your Convex team with one team access token. A team access token belongs to one team, so one token connects one team. Polylane encrypts the token before it stores it, and the agent never sees it.
- In the Convex dashboard, go to Team Settings → Access Tokens.
- Click Create access token and copy the token.
- Paste the token into Polylane. Polylane checks the token and starts the first sync.
A team access token gives management access to the team.
Connect Convex from a CI job or any other environment without a browser.
Connecting Convex needs no browser: the same endpoint the console calls fits in a CI job. One authenticated POST creates the connection and starts the first sync.
Prerequisites
- A Polylane API key with the
cloud_accounts:writeandcloud_accounts:readscopes. See API keys and OAuth. - Your workspace ID, which starts with
ws_. Read it fromGET /v1/workspaceswith the same key. - A Convex team access token from Team Settings → Access Tokens.
Create the connection
curl -X POST https://api.polylane.com/v1/cloud_accounts \
-H "x-api-key: $POLYLANE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "convex",
"workspaceId": "ws_0abc123",
"token": "<team-access-token>"
}'
A team access token is scoped to exactly one team, so one call connects one team.
The response lists what was connected, with the first sync already running. Trimmed to the two fields the rest of the flow reads:
{
"success": true,
"result": {
"provider": "convex",
"accounts": [{ "id": "acc_34gky74ibc92h8t2efn8csrh", "status": "syncing" }],
"failures": []
}
}
An account that is already connected lands in failures instead of accounts, so repeating the call never duplicates a connection.
Wait for the first sync
Poll each returned account by its id until status reaches ready (new on registration, syncing while resources stream in):
until [ "$(curl -s "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
-H "x-api-key: $POLYLANE_API_KEY" | jq -r '.result.status')" = "ready" ]; do
sleep 15
done
Give the loop a deadline so a failed connect fails the job instead of hanging it. Once the account is ready, its resources are in the topology and Polylane has started its first check.
Disconnect from the API
Deleting the connection stops every sync and check and deletes the credentials Polylane held. The call needs the cloud_accounts:delete scope:
curl -X DELETE "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
-H "x-api-key: $POLYLANE_API_KEY"
Then delete the Convex token, as described under Disconnecting.
How it works
Resources in the context graph
Polylane maps your projects and, in each project, its cloud deployments: production, preview, development and custom deployments, with their region, URL and deployment class. Local deployments run on the machines of your developers, so Polylane does not sync them. Polylane syncs every 15 minutes.
Scoped deploy keys
Sync uses the team access token. To read the logs, metrics or data of one deployment, Polylane creates a deploy key for that deployment with only the permission that the read needs: view logs, view metrics or view data. Polylane deletes the key after the read. Each key also expires after 35 minutes. Its name starts with polylane-ephemeral-.
Anomaly detection
Each deployment gets its own monitor. Polylane reads the function failure rate, the query cache hit rate, the scheduled job lag and the function logs, and compares each series with its usual level. It opens an issue when a change is a real problem.
Polylane monitors only production deployments until you turn on Preview and dev deployments in the account settings. Preview and development deployments stay in the graph either way.
What agents can do
During an investigation, agents read function logs, function metrics (invocations, errors, latency, cache hit rate and scheduled job lag) and the team audit log. Agents can also read your data: list the tables of a deployment with their document shapes, read the newest or oldest documents of a table, and run a one-off query. Convex runs that query as a sandboxed query function, so it cannot write data or reach the network.
Agents can request changes through the Convex Management API. The account is read-only by default, and each change needs safety review and approval before it runs.
Troubleshooting
"Not a team access token" error
- A project token or a deploy key cannot list the projects of the team. Create the token under Team Settings → Access Tokens.
- Check that the token is not deleted in the Convex dashboard.
- Make sure you copied the full token.
Missing resources
- A project without a deployment shows no deployments until the first
npx convex devornpx convex deploy. - Click Sync in the account header to sync before the next scheduled sync.
Disconnecting
Disconnecting does not change Convex. Delete the access token under Team Settings → Access Tokens in the Convex dashboard.
Disconnect
Disconnecting stops every sync and check and deletes the credentials Polylane held. Everything Polylane set up in Convex is removed as well; nothing is left behind.
polylane cloud disconnect <id>Tools
6Operations agents can perform in threads.
Supported resources
2Resource types that show up in your infrastructure graph.