> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basecut.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# basecut agent

> Start a Basecut self-hosted agent

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.

<Info>The self-hosted agent requires a **TEAM** plan.</Info>

## Usage

```bash theme={null}
basecut agent [flags]
```

***

## 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:

```bash theme={null}
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):

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
✓ Agent started (ID: agent_abc123)
✓ Registered with Basecut API
⣾ Polling for jobs... (interval: 5s)
```

### Processing a Job

```bash theme={null}
✓ 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

<CardGroup cols={2}>
  <Card title="Deployment Guide" icon="server" href="/advanced/agent-deployment">
    Deploy agents using Docker and Kubernetes
  </Card>

  <Card title="Execution Modes" icon="bolt" href="/core-concepts/execution-modes">
    Understand how agents process jobs
  </Card>
</CardGroup>