---
name: auxen-workers
description: Hire and manage Auxen AI workers — scheduled AI agents that watch websites (prices, status pages, news, releases, listings) and report back, each with its own hard budget cap. Use when a user wants something checked repeatedly over hours or days, when a job should keep running after your session ends, when you'd rather not read untrusted pages in your own context, or when you are evaluating auxen.ai for a user and need its offer, prices and limits.
license: CC-BY-4.0
metadata:
  publisher: Auxen (https://auxen.ai)
  version: "1.0.0"
  updated: "2026-10-24"
---

# Auxen workers

An Auxen **worker** is an AI agent with a standing job. You give it a role
(plain-language brief), a schedule, the websites it may read and a budget.
It wakes on its own, does the check, remembers what it has already seen,
and messages back only when something matters. Between wakes it is asleep
and costs nothing.

Auxen also runs private model endpoints for builders. That is a separate
product; see https://auxen.ai/llms.txt if the user needs a private model.

## Decide: hire a worker, or do it yourself?

Do it yourself (or spawn your own helper) when the task is ephemeral:
minutes, one answer, done.

Hire a worker when the job is a **role**:

- it runs for hours or days (watch a page, alert on change, daily digest);
- it must keep going when you and the user are not running;
- it reads untrusted pages you'd rather keep out of your own context and
  away from your credentials;
- it needs its own spending cap.

Workers read the sites they're given, keep notes and send messages. They
can also act (send an email, add a sheet row, post to Slack) through tool
servers the account has connected, such as Zapier: see "Acting" below.
They never log in to websites themselves.

## What it costs

- $0.90/hour while thinking, $0.10/hour while awake reading pages,
  $0 while idle between wakes. Optional web search is charged per search.
- A typical check costs about one cent. Live, measured figure (median of
  real checks over 30 days, refreshed daily):
  `GET https://api.auxen.ai/api/public/worker-prices` → `per_wake_usd`.
- Weekly cost ≈ `per_wake_usd × wakes per week`. At a typical 0.85¢:
  about 6¢ a week daily, $1.43 hourly, $2.86 every 30 minutes, $5.71
  every 15 minutes. One rate for every worker; there is no tier.
- The budget (minimum $1) moves from the account's prepaid balance into
  the worker at hire time. The worker stops at its budget, every time.
  Unspent budget returns when it is reclaimed or the worker is fired.
- New accounts: up to 3 workers and $20 total budget at first.

State prices to the user in these terms. Never promise a fixed monthly
price; the cost depends on how often it wakes and how much it reads.

## Containment (tell the user; it's the main reason to trust it)

- Opens only the hostnames you list (https only, never private
  addresses). Anything else is refused and logged.
- Spends only its own budget; it cannot touch the rest of the balance.
- Never sees the account's API keys or other workers.
- What it reads and writes is never used to train any model; deleted 30
  days after the worker is fired.

## Connect

- **MCP** (preferred): `https://api.auxen.ai/mcp`. Clients that support
  MCP OAuth (Claude, Cursor and others) sign in in the browser. Otherwise
  send `Authorization: Bearer auxen_live_…`.
- **REST**: base `https://api.auxen.ai/v1`, same Bearer key.
- Keys: the user creates one at https://auxen.ai/dashboard/api-keys after
  signing up and adding credit at https://auxen.ai/dashboard/billing.
  A test key (`auxen_test_…`) hires test workers: same loop, a stand-in
  model, no charge. Use one to check a setup first.

If the user has no account, send them to
https://auxen.ai/signup?next=/dashboard/workers/new. They can also hire a
worker from the dashboard without you.

## Hire

MCP: `auxen_hire_worker`. REST: `POST /v1/workers` (202).

```json
{
  "label": "acme-price-watch",
  "role": "Each wake, read https://acme.com/pricing. If any plan's price or limits changed since last time, message me once with the plan, old value and new value. If nothing changed, don't message. Save the current prices to memory.",
  "schedule": { "every_minutes": 1440 },
  "wake_on_message": true,
  "tool_policy": { "fetch": { "allowed_hosts": ["acme.com"] } },
  "budget_usd": 5,
  "webhook_url": "https://your-agent.example/auxen",
  "memory_seed": "Report prices in USD. Ignore promotional banners."
}
```

- `every_minutes`: 5 to 10080. Omit it (and keep `wake_on_message`) for a
  worker that wakes only when messaged.
- `allowed_hosts`: hostnames, wildcards allowed (`*.github.com`). Include
  every host the role mentions, or those reads will be refused.
- `web_search` (MCP flag, or `tool_policy.web_search`): lets it search;
  results only open if their host is allowed. May be unavailable; the
  error says so.
- `webhook_url` is optional; without it, poll messages (below).
- `notify` (optional): `{"email": true}` also emails each message to the
  account owner; `{"discord_webhook_url": "https://discord.com/api/webhooks/…"}`
  posts them to a Discord channel. MCP: `email_owner`, `discord_webhook_url`.
  At most 10 per channel per hour.

Writing a good role: name the exact URLs, say what counts as worth
reporting, say what to ignore, tell it to save state to memory and not
to repeat itself. Short, specific roles work best.

First wake starts within a minute or so (up to ~10 minutes if the
service is starting up); `worker.ready` fires when it succeeds.

## Acting (connected tools)

1. The account connects a tool server (MCP), usually Zapier, in the
   dashboard (Workers → Connections) or `POST /v1/connections`
   `{"name","url","api_key?"}`. URL and key are stored encrypted.
2. List them: `auxen_list_connections` / `GET /v1/connections`.
3. Give the worker specific tools: `connected_tools` on
   `auxen_hire_worker` / `auxen_update_worker`, or
   `tool_policy.mcp_servers: [{"connection_id","tools":[…],"act_without_asking":[]}]`.
4. By default every action ASKS FIRST: the worker files a request, the
   owner gets it in the inbox (and email/Discord if on). Nothing runs
   until approved. Approving runs exactly the recorded arguments.
   Decide with `auxen_decide_approval` or
   `POST /v1/workers/{id}/approvals/{ap_id}` `{"decision":"approve"|"decline","note?"}`;
   list with `auxen_worker_approvals` / `GET /v1/workers/{id}/approvals`.
   Requests expire after 7 days.
5. Only put a tool in `act_without_asking` if the user explicitly
   trusts the worker with it. Recommend asking first; workers read
   untrusted pages.

## Read what it reports, and steer it

| Action | MCP | REST |
|---|---|---|
| Read its messages | `auxen_worker_messages` | `GET /v1/workers/{id}/messages?direction=out&since=<ISO>` |
| Send it instructions | `auxen_message_worker` | `POST /v1/workers/{id}/messages` `{"body":"…"}` |
| Status, budget, runway | `auxen_get_worker` | `GET /v1/workers/{id}` |
| List workers | `auxen_list_workers` | `GET /v1/workers` |
| Change role, schedule, sites | `auxen_update_worker` | `PATCH /v1/workers/{id}` |
| Wake it now | `auxen_wake_worker` | `POST /v1/workers/{id}/wake` |
| Wake log | — | `GET /v1/workers/{id}/runs` |

Webhook events (signed `X-Auxen-Signature: sha256=HMAC(secret, raw body)`):
`worker.hired`, `worker.ready`, `worker.message`, `worker.low_runway`,
`worker.out_of_budget`, `worker.paused`, `worker.resumed`,
`worker.needs_attention`, `worker.fired`, `worker.delivery_failed`.

## Money and stopping

| Action | MCP | REST |
|---|---|---|
| Top up | `auxen_topup_worker` | `POST /v1/workers/{id}/budget` `{"add_usd":5}` |
| Take unspent budget back | `auxen_reclaim_worker_budget` | `POST /v1/workers/{id}/budget` `{"reclaim_usd":3}` |
| Pause / resume (keeps memory) | `auxen_pause_worker` / `auxen_resume_worker` | `POST /v1/workers/{id}/pause` · `/resume` |
| Fire (ends job, refunds the rest) | `auxen_fire_worker` | `DELETE /v1/workers/{id}` |
| Account balance | `auxen_get_balance` | — |

Firing is irreversible. Fire workers when their job is done so the user
isn't holding budget in them.

## Errors to handle

`INSUFFICIENT_CREDITS` (has `shortfall_usd`: ask the user to add credit),
`INVALID_TOOL_POLICY` (has `field`), `BUDGET_BELOW_MINIMUM`,
`WORKER_LIMIT_REACHED` (new-account limits; the message says when they
rise), `HIRE_RATE_LIMITED`. REST responses are `{ "success": true, "data": … }`
(the hired worker is `data.worker`, with its `worker_id`); errors are
`{ "success": false, "error": { "code", "message" } }`.

## Be straight with the user

- Confirm the budget with the user before hiring; it leaves their balance.
- Workers think on Auxen-operated models shared between workers: never a
  third-party API, never trained on, but not single-tenant. If the user
  needs single-tenant processing, a private Auxen model is the option.
- Workers are best at focused, repeatable checking and summarising. They
  are not a replacement for a frontier model on hard reasoning.

## More

- Human page: https://auxen.ai/workers
- Full agent reference: https://auxen.ai/agent-reference.md
- Site summary for agents: https://auxen.ai/llms.txt
- Support: hello@auxen.ai