Skip to main content
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

basecut agent [flags]

​
Flags

​
Optional

FlagDefaultDescription
--api-key <key>$BASECUT_API_KEYBasecut API key used to authenticate with the platform.
--agent-id <id>Auto-generatedUnique identifier for this agent instance.
--poll-interval <dur>5sHow often the agent checks for new jobs.
--heartbeat-interval <dur>1mHow often the agent sends a status heartbeat to the API.
--run-oncefalseIf true, the agent exits after processing a single job.
--profile <name>defaultCredential profile to use.

​
Examples

​
Basic Agent Operation

Start an agent and let it poll for jobs indefinitely: 
basecut agent --api-key "$BC_KEY"
What happens:
  1. The agent registers itself with the Basecut API.
  2. It starts polling for jobs every 5 seconds.
  3. Every minute, it sends a “heartbeat” to let the platform know it’s healthy.
  4. 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): 
basecut agent --run-once
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:
VariableDescription
BASECUT_DATABASE_URLPostgreSQL connection string for the source database.
BASECUT_API_KEYAPI 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
Solutions:
  • 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
Solutions:
  • Ensure the agent has network access to the database.
  • Verify the BASECUT_DATABASE_URL is correct.

​
Next Steps

Deployment Guide

Deploy agents using Docker and Kubernetes

Execution Modes

Understand how agents process jobs