The Basecut agent is a long-running process that waits for and executes remote snapshot jobs. It is typically deployed as a Docker container or Kubernetes pod within your private network, allowing it to connect to your database while keeping credentials secure.
The self-hosted agent requires a TEAM plan.
Usage
Flags
Optional
| Flag | Default | Description |
|---|
--api-key <key> | $BASECUT_API_KEY | Basecut API key used to authenticate with the platform. |
--agent-id <id> | Auto-generated | Unique identifier for this agent instance. |
--poll-interval <dur> | 5s | How often the agent checks for new jobs. |
--heartbeat-interval <dur> | 1m | How often the agent sends a status heartbeat to the API. |
--run-once | false | If true, the agent exits after processing a single job. |
--profile <name> | default | Credential profile to use. |
Examples
Basic Agent Operation
Start an agent and let it poll for jobs indefinitely:
basecut agent --api-key "$BC_KEY"
- The agent registers itself with the Basecut API.
- It starts polling for jobs every 5 seconds.
- Every minute, it sends a “heartbeat” to let the platform know it’s healthy.
- When a job is received, it executes the extraction based on the provided configuration.
Run-Once (CI/CD or Job-Based)
In some environments, you might want to start an agent only when you know a job is waiting (e.g., in a transient CI container):
Behavior:
- The agent will poll for a job.
- Once a job is completed (or fails), the agent process terminates immediately.
Custom Polling Interval
For high-priority environments or to reduce API overhead, adjust the polling frequency:
basecut agent --poll-interval 1s --heartbeat-interval 30s
Required Environment Variables
The agent requires access to the database it will be extracting data from:
| Variable | Description |
|---|
BASECUT_DATABASE_URL | PostgreSQL connection string for the source database. |
BASECUT_API_KEY | API Key (if not provided via flag). |
Output
Normal Startup
✓ Agent started (ID: agent_abc123)
✓ Registered with Basecut API
⣾ Polling for jobs... (interval: 5s)
Processing a Job
✓ Job received: job_xyz789
✓ Processing extraction... (2,847 rows)
✓ Uploading snapshot to s3://my-bucket/snapshots/
✓ Job completed successfully
⣾ Polling for jobs...
Error Handling
Authentication Failure
✗ Error: failed to register agent
Unauthorized: Invalid API key
- Verify your
BASECUT_API_KEY is correct and active.
- Check that your plan supports self-hosted agents.
Database Connection Loss
✗ Error: job failed
could not connect to database: connection refused
- Ensure the agent has network access to the database.
- Verify the
BASECUT_DATABASE_URL is correct.
Next Steps
