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

​
Flags

​
Optional

​
Examples

​
Basic Agent Operation

Start an agent and let it poll for jobs indefinitely:
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):
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:

​
Required Environment Variables

The agent requires access to the database it will be extracting data from:

​
Output

​
Normal Startup

​
Processing a Job

​
Error Handling

​
Authentication Failure

Solutions:
  • Verify your BASECUT_API_KEY is correct and active.
  • Check that your plan supports self-hosted agents.

​
Database Connection Loss

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