# TaskGoblin Documentation > The full TaskGoblin documentation as Markdown, for large language models. # Introduction Source: https://taskgoblin.ai/en/docs/introduction Stop prompting agents. Start engineering loops. The difference is the whole product. A prompt gets you one answer, once, and only if someone remembers to type it. A **loop** is a trigger plus an instruction — it fires on its own, does the work in an isolated cloud sandbox, opens a merge request you review, writes down what it learned, and is ready for the next turn. You do not open an app or paste code into a chat window. You connect the tools your team already uses, and the work starts happening in them. ## A loop is a trigger and an instruction - The **trigger** is either an **event** — a pull request opened, an issue assigned to the goblin — or a **schedule**, like every weekday at 07:00. - The **instruction** is plain English, not a DSL. *"Review this merge request for correctness and security — flag real problems, not style nits."* Or: *"Check `acme/web` for safe dependency upgrades and open a merge request."* Everything TaskGoblin does is one of these. Automatic code review is an event loop on *pull request opened*. Assigning an issue and getting a merge request back is an event loop on *issue assigned*. Overnight test-suite health is a schedule loop at 06:00. There is no separate "automation feature" bolted on the side — loops are the primitive, and the behaviours that feel built-in are loops you own and can rewrite. [Loops](/en/docs/loop-engineering) is the page to read next if you read only one. ## You start with loops already running Sign in with GitLab or GitHub and TaskGoblin provisions your organisation, connects your repositories, and installs that provider's default loops — reviewing merge requests, picking up assigned issues. Open a pull request and it gets reviewed before you have configured anything. Those defaults are ordinary loops on your Loops page. Read the instruction, rewrite it in your own words, pause it, delete it. Owning the behaviour is the point. ## What a loop actually looks like Loops are written in plain English, not a DSL. Here is a real one from the template gallery — a nightly guard on your test suite: > **Trigger** — every day at 06:00 > > **Instruction** — *Clone `acme/web`, run the full test suite on the default branch. If something fails and the fix is small and safe, open an MR; otherwise summarise the failures. If all pass, do nothing.* Three sentences, and look at what is packed into them: where to work, what to do, when to fix versus when to escalate, and — the single most important line in any unattended instruction — **permission to do nothing**. That last clause is why you get a merge request on the mornings something broke, and silence on the mornings it did not. The gallery ships nine of these to start from: dependency upgrades, docs drift, changelog entries, tech-debt sweeps, activity digests, stale-review reminders, triage nudges. All editable, all yours the moment you pick one. See [Schedule loops](/en/docs/schedule-loops) for the full set, worked through. ## Why the loops run in the cloud Because a goblin runs in an isolated cloud sandbox rather than on someone's laptop, the work is: - **Asynchronous** — hand it off and close your machine. - **Isolated** — one boundary per organisation, and your credentials are injected around the agent, never handed to it to read. - **Parallel** — every run gets its own branch and sandbox, so ten loops firing at once is ten goblins working, not a queue. - **Always on** — 03:00 maintenance and a review of the pull request opened at midnight both happen without anyone awake. ## What arrives at the end of a turn A branch and a merge request, reviewed exactly like a colleague's — or inline review comments, or a reply in the Slack thread where you asked. Never a wall of text you have to act on yourself, and never a commit to your default branch. Under the hood it is a real coding agent (Claude Code, Codex, or Gemini) with a checkout of your repository, reading files, running commands and tests, and working the problem the way a contributor does. Because it has its own identity in each tool — `@taskgoblin` on GitLab, Slack and Teams, `taskgoblin[bot]` on GitHub — the whole team can delegate to it and the whole team can see what it did. ## Where to go next **Start here** - **[Quickstart](/en/docs/quickstart)** — from sign-in to your first reviewed pull request and your first schedule loop. - **[Loops](/en/docs/loop-engineering)** — the primitive, and why it beats a prompt. **Build your loops** - **[Event loops](/en/docs/event-loops)** — reviews, assignments, and labels; the defaults you already have and how to change them. - **[Schedule loops](/en/docs/schedule-loops)** — recurring work, and templates to start from. - **[Connect your integrations](/en/docs/connect-your-integrations)** — GitLab, GitHub, Linear, Jira, Slack, and Microsoft Teams. - **[Ad-hoc runs](/en/docs/ad-hoc-runs)** — asking directly, when the work really is a one-off. **Understand the machinery** - **[How a run works](/en/docs/how-the-agent-works)** — inside a single turn of a loop. - **[The cloud sandbox](/en/docs/the-cloud-sandbox)** — where your code runs, and how it stays isolated. - **[The brain](/en/docs/the-brain)** — how a correction sticks for every goblin after it. **Billing** - **[Pricing and credits](/en/docs/pricing-and-credits)** — you pay for time, not tokens. - **[Bring your own LLM account](/en/docs/bring-your-own-llm-account)** — and pay a lower rate. - **[Bring your own sandbox server](/en/docs/bring-your-own-sandbox-server)** — run goblins on your own infrastructure. - **[Automatic top-up](/en/docs/automatic-top-up)** — keeping unattended loops from stalling. # Quickstart Source: https://taskgoblin.ai/en/docs/quickstart This quickstart takes you from a fresh account to loops running on your repositories. Most of the few minutes it takes is spent waiting for a goblin, not on setup. ## Before you start You need admin access to a GitLab group or a GitHub organisation whose repositories you want the goblins working on. That is all — nothing to install locally, and no keys to copy anywhere. ## Step 1 — Sign in Go to the login page and sign in with **GitLab** or **GitHub**. That single consent does three things: it logs you in, provisions an organisation with your repositories connected, and installs that provider's **default loops**. - On **GitHub** you install the TaskGoblin GitHub App on the organisation you want; the installation is the bot identity that posts as `taskgoblin[bot]`. - On **GitLab** the OAuth consent enumerates your groups and connects them; the goblin posts as `@taskgoblin`. ## Step 2 — Look at the loops you already have Open the **Loops** area of your organisation. You will find loops nobody configured: - **Review merge requests** / **Review pull requests** — fires whenever one is opened or updated. - **Work on assigned issues** / **Work on labelled issues** — fires when an issue is handed to the goblin. Open one. The instruction is plain English and completely yours to change — this is the moment the product stops looking like a black box. ## Step 3 — Watch a loop fire Open a pull request on a connected repository, or push a new commit to one that is already open. You do not have to mention anyone or press anything. Within a minute or two a goblin clones the repository in an isolated cloud sandbox, reads the diff in context, and posts a review: a summary plus inline comments where they earn their place. If it has nothing worth saying, it says nothing — that restraint is written into the default instruction, and you can dial it up or down. Reply `@taskgoblin fix` to any inline comment and it implements that one finding and pushes the commit. ## Step 4 — Hand off an issue Now try the other default loop. Add the `taskgoblin` label to a GitHub issue, or assign a GitLab issue to the `@taskgoblin` bot. If your team lives in Linear or Jira, connect it from **Integrations** first — connecting either one installs its *Work on assigned issues* loop — then assign an issue there. The goblin works on a dedicated branch named after the issue, commits, pushes, and opens a merge request linked back to it, posting progress as it goes. Review it exactly as you would a colleague's. ## Step 5 — Build a loop of your own The defaults cover the reactive work. The compounding value is in the work nobody currently remembers to do — so create one: 1. Go to **Loops** and create a new one. 2. Pick a template. **Test-suite health** (daily) and **Dependency upgrades** (weekly) are the two most teams keep. 3. Replace the `{group/repo}` placeholder with a real repository, adjust the cadence to your timezone, and save. Tomorrow morning there is either a merge request waiting or, if there was nothing to do, silence. Both are correct — the templates are written to do nothing rather than manufacture busywork. ## What you just did You did not learn a new interface or write a prompt. You inherited two loops, watched one work, and built a third. Everything else in these docs is detail underneath that: [what a loop is](/en/docs/loop-engineering), [the events you can fire on](/en/docs/event-loops), [the cadences you can run](/en/docs/schedule-loops), and [what happens inside a single turn](/en/docs/how-the-agent-works). # Loops Source: https://taskgoblin.ai/en/docs/loop-engineering Most AI coding tools are built around a prompt. You describe what you want, an agent answers, and the exchange is over. That works right up to the moment the valuable thing stops being *one good answer* and starts being *the same work happening reliably, every time, without anyone remembering to ask*. TaskGoblin is built around a **loop** instead. ## A loop is a trigger and an instruction That is the entire primitive. - A **trigger** decides when the goblins wake up. It is either an **event** — a pull request was opened, an issue was assigned to the goblin — or a **schedule**: every weekday at 07:00. - An **instruction** is plain English describing what to do when they do. *"Review this merge request for correctness and security — flag real problems, not style nits a linter would catch."* Or: *"Check `acme/web` for safe dependency upgrades, run the tests, and open a merge request."* Put the two together and you no longer have a request, you have a standing capability. Nobody has to be at a keyboard, and nobody has to remember. ## Everything is a loop This is not a feature sitting beside the product — it *is* the product. The behaviours you would assume are hardcoded platform magic are all ordinary loops: | What it looks like from the outside | The loop underneath | | --- | --- | | Every pull request gets reviewed | An **event loop** on *pull request opened* | | Assign an issue to the goblin, get a merge request back | An **event loop** on *issue assigned* | | Dependencies stay current without a ticket | A **schedule loop** every Monday at 08:00 | | The docs never drift from the code | A **schedule loop** every Wednesday | | A digest of what moved lands in Slack each morning | A **schedule loop** at 09:00 | When you connect GitLab or GitHub, TaskGoblin installs a starter set of these for you — which is why code review begins working before you have configured anything at all. They are not special. Open them, read the instruction, rewrite it in your own words, pause it, or delete it. ## One turn of a loop Every turn runs the same way, whether the trigger was a webhook or a clock, and whether it is the first turn or the five-hundredth: 1. **Fire.** The trigger matches. TaskGoblin opens — or reuses — a thread for that piece of work. 2. **Context.** The goblin reads the issue, the thread, the diff, your organisation's conventions, and the notes previous goblins left, before it touches anything. 3. **Work.** It runs inside an isolated cloud sandbox holding a checkout of your repository: reading files, editing them, running commands and tests. 4. **Deliver.** It opens a merge request, posts inline review comments, or replies in the thread — wherever that work belongs. 5. **Hand off.** It writes down what it learned and what is still open, so the next turn starts from there instead of from zero. Step 5 is what separates a loop from a cron job. Each turn is informed by the ones before it, so a loop that runs every week for a year is not the same loop a hundred times — it is one that has been paying attention. ## Why a loop beats a prompt - **It runs without you.** The work is already done by the time you look, rather than waiting on someone noticing it needs doing. - **It is reviewable.** Every turn ends as a branch and a merge request, reviewed exactly like a colleague's. Nothing merges on its own. - **It compounds.** Correct a goblin once and the correction is written down for every goblin after it. - **It has an off switch.** A loop is a row you own. Pause it and the behaviour stops immediately. ## Where loops live Manage them from the **Loops** area of your organisation (`/{organisation}/loops`). Every loop has its own page: the instruction, the trigger, an Active toggle, and the history of its recent runs, so you can see what it actually did rather than trusting that it fired. Goblins can also create loops themselves mid-run. A goblin that notices you asking for the same thing every Friday can propose the loop that removes the asking. ## Where to go next - **[Event loops](/en/docs/event-loops)** — loops that fire on a pull request, an assigned issue, or a label, and the defaults you already have. - **[Schedule loops](/en/docs/schedule-loops)** — loops that fire on a cadence, and the templates to start from. - **[Ad-hoc runs](/en/docs/ad-hoc-runs)** — the direct asks that are not loops, and how to tell when one wants to become one. - **[How a run works](/en/docs/how-the-agent-works)** — what happens inside a single turn. # Event loops Source: https://taskgoblin.ai/en/docs/event-loops An **event loop** fires when something happens in a tool you have connected. No cadence, no assignment ritual, no one typing a prompt: a pull request is opened and the review is underway before anyone has switched tabs. Its instruction is standing guidance layered on top of whatever the event already carries. The goblin is given the merge request or the issue as context automatically; your instruction tells it what *you* want done about it. ## The events you can loop on | Event | Source | Fires when | | --- | --- | --- | | Merge request opened | GitLab | An MR is opened, reopened, or updated with new commits | | Issue assigned | GitLab | An issue is assigned to the `@taskgoblin` bot | | Pull request opened | GitHub | A PR is opened, reopened, or updated with new commits | | Issue labelled | GitHub | The `taskgoblin` label is added to an issue | | Issue assigned | Linear | An issue is assigned to the TaskGoblin agent | | Issue assigned | Jira | An issue is assigned to the TaskGoblin account | Because the "opened" events also cover updates, a review loop reconciles rather than repeats: on a second pass it reads the findings it left last time, resolves the ones you have fixed, and only posts what is genuinely new. ## The loops you already have You do not start from an empty page. The moment a provider comes into existence for your organisation, TaskGoblin seeds that provider's default loops: - **GitLab** — *Review merge requests* and *Work on assigned issues*. - **GitHub** — *Review pull requests* and *Work on labelled issues*. - **Linear** — *Work on assigned issues*. - **Jira** — *Work on assigned issues*. These reproduce what people expect a coding agent to do out of the box. The difference is that they are yours: real loops on your Loops page, with instructions you can read and change. Seeding happens once, ever. Delete a default loop and it stays deleted — reconnecting the provider will not quietly bring it back. ## Rewriting the instruction is the point The default review instruction asks for correctness, security, and maintainability, and tells the goblin to stay silent when a change is sound. That is a reasonable opening position, not a policy you are stuck with. Teams routinely narrow or widen it: - *"Only flag security issues and data-loss risks. Nothing else."* - *"Be strict about test coverage — every behaviour change needs a test, say so if one is missing."* - *"Also check that any new endpoint is covered by our rate-limiting middleware."* The instruction is free text, so it can encode the things a linter cannot: your conventions, your past incidents, the mistake this team keeps making. ### The default, and a hardened version of it This is what ships: > Review this merge request. Focus on correctness, security, and maintainability — flag real problems, not style nits a linter would catch. Leave inline comments only where they add value, keep them specific and actionable, and stay silent when the change is sound. It is deliberately restrained, because a reviewer that comments on everything gets muted. Now here is the same loop after a team has lived with it for a month and had an incident: > Review this merge request for correctness, security, and maintainability. Flag real problems, not style nits. > > Additionally, always check: every behaviour change has a test; no new endpoint ships without our rate-limiting middleware; no migration edits an existing migration file; nothing logs a full request body. Raise these as **critical** even when the rest of the change is fine. > > If the MR is over 400 lines, say so in the summary and review the riskiest files first rather than skimming everything. Stay silent when the change is sound. Nothing about the second version is exotic — it is institutional knowledge that previously lived in a wiki nobody opened, now attached to the moment it matters. That is the difference between a loop you inherited and a loop you own. ## The off switch This is the part worth reading twice, because it explains behaviour that would otherwise look like a bug. **A gated event with no matching active loop starts no run.** Pause your review loop and merge requests stop being reviewed. Delete it and the same. TaskGoblin still accepts the webhook — it simply has no standing instruction to act on, so no goblin wakes and nothing is billed. That is the trade for owning the behaviour rather than having it done to you. If automatic review has stopped, the first place to look is whether its loop is still active. ## What is never gated Explicit human asks always run, whether or not any loop exists: - `@taskgoblin` mentioned on a merge request, pull request, or issue comment - A message or mention in Slack or Microsoft Teams - A follow-up comment on a Linear issue the goblin is already working - A mention on a Jira issue comment - Replying `@taskgoblin fix` to one of its own review comments If a person asked directly, a goblin answers. Loops govern the *unprompted* work, and only that. ## When several loops match Nothing stops you running more than one loop on the same event — a general review loop plus a stricter one for security, say. When an event matches several, the goblin is shown all of the candidate instructions and judges which applies, recording the choice on the run so the history stays honest. The work still happens as a single run: loops do not multiply into duplicate reviews on one merge request. ## Where to go next - **[Schedule loops](/en/docs/schedule-loops)** — the other trigger kind, for work no event announces. - **[Connect your integrations](/en/docs/connect-your-integrations)** — which providers you can loop on, and what each one unlocks. - **[Ad-hoc runs](/en/docs/ad-hoc-runs)** — the direct asks that bypass loops entirely. # Schedule loops Source: https://taskgoblin.ai/en/docs/schedule-loops Some work is announced by an event: a pull request is opened, an issue is assigned. Plenty is not. Nothing fires a webhook when your dependencies drift a month behind, when the README stops matching the code, or when a test has been quietly skipped since March. A **schedule loop** is the trigger for that work. Same instruction, same run, same reviewable merge request — the clock just takes the place of the webhook. ## One-time and recurring - **One-time** — run an instruction once at a future moment. *"Draft the release notes at 17:00 on Friday."* It deactivates itself after firing. - **Recurring** — run **daily**, **weekly**, or **monthly** at a time you choose. Every loop carries its own **timezone**, so "09:00 weekly" means nine in the morning where your team actually is, and it keeps meaning that across daylight-saving changes. A missed minute is skipped, not backfilled. If a loop could not fire — the platform was down, the schedule moved — the next occurrence runs normally rather than replaying every fire you missed at once. ## Start from a template You do not need to write a good instruction from a blank page. The create screen ships a gallery of starter loops, each with a cadence and a full instruction you then edit: | Template | Cadence | What it does | | --- | --- | --- | | **Dependency upgrades** | Weekly, Monday 08:00 | Safe patch and minor bumps, runtime and dev deps in separate MRs, tests run before opening | | **Test-suite health** | Daily, 06:00 | Runs the full suite on the default branch; opens an MR if the fix is small and safe, otherwise reports | | **Docs drift** | Weekly, Wednesday | Compares the README and docs against the last seven days of merges and fixes what is now wrong | | **Changelog / release notes** | Weekly, Friday 16:00 | Opens an MR adding a CHANGELOG entry for the week's merges | | **Tech-debt sweep** | Weekly, Monday | New TODO/FIXME and skipped tests — an MR for the safe ones, a list of the rest | | **Daily activity digest** | Daily, 09:00 | A high-signal 24h summary posted to a Slack channel | | **Stale-MR reminder** | Daily, 10:00 | Open MRs idle for three days or more, posted to Slack | | **Linear triage nudge** | Daily, 09:00 | Comments on issues missing a label or an estimate | | **Reminder** | Daily | A plain recurring nudge to Slack or email | Templates use `{placeholders}` — `{group/repo}`, `{#channel}`, `{team}` — that you replace with your own. Every field stays editable after you pick one. ## Four of them, worked through The instructions are the interesting part. These are shipped verbatim; read them as models for your own. ### Dependency upgrades — scoping a change that touches everything > In `{group/repo}`, check for safe patch and minor dependency upgrades. Put runtime and dev deps in separate merge requests, run the test suite to verify, and open the MRs. No major-version bumps, no unrelated refactoring. If nothing is upgradable, do nothing. Dependency work is where an unsupervised agent can do the most damage, so almost every clause here is a boundary. *Separate merge requests* means a broken dev dependency never blocks a security patch. *Run the test suite to verify* makes the goblin prove the bump before asking for your attention. *No major-version bumps, no unrelated refactoring* rules out the two ways this task classically sprawls — and it is worth noticing that the loop is more disciplined about scope than most humans doing the same chore on a Friday afternoon. ### Test-suite health — deciding when to escalate instead of fix > Clone `{group/repo}`, run the full test suite on the default branch. If something fails and the fix is small and safe, open an MR; otherwise summarise the failures. If all pass, do nothing. This one encodes a judgement call rather than a procedure. A flaky assertion gets fixed; a genuine regression in payment handling gets *reported*, because "small and safe" is the goblin's own bar to clear and it is instructed to fall back to telling you rather than attempting a heroic fix at 6am. Loops are more useful when they know what they should not attempt. ### Daily activity digest — teaching it what counts as signal > Summarise MRs merged/opened in `{group/repo}` in the last 24h into a short, high-signal digest and post it to `{#channel}` with `slack-send-message`. High-signal only (merged, ready-for-review, unblocked, recurring CI failures); skip label/assignment churn and bot noise. If nothing meaningful happened, don't post. A digest that reports everything is a digest nobody reads by week three. This instruction defines signal by enumerating both sides — what to include *and* what to drop — and then closes the loop with the clause that keeps it trustworthy: on a quiet day it stays quiet. An automation that posts "no activity today" every Sunday has already trained your team to ignore it. ### Linear triage nudge — capping the blast radius > Review Linear issues in `{team}` updated in the last day that are missing a label or estimate, and comment on each with `linear-comment` asking for the missing detail. Inspect at most 30 issues; comment on at most 10. If none need attention, do nothing. Note the two hard numbers. Without them, a loop pointed at a neglected backlog would work through six hundred issues on its first run and leave a comment on every one — technically correct, socially a disaster, and expensive. *Inspect at most 30, comment on at most 10* keeps the first run indistinguishable from the hundredth. Anywhere a loop touches things people will see, put a number on it. ## Writing an instruction that behaves overnight Read those four again and the house style falls out. Unattended work deserves more explicit boundaries than a request you are sitting next to: - **Name the repository.** A schedule loop has no issue and no thread to infer one from, so say `{group/repo}` outright. - **Cap the blast radius.** *"Touch at most a handful of files."* *"Comment on at most 10."* - **Say what is out of scope.** *"No major-version bumps, no unrelated refactoring."* - **Say when to report instead of act.** *"If the fix is small and safe, open an MR; otherwise summarise."* - **Give it permission to do nothing.** *"If nothing is upgradable, do nothing."* This is the single most valuable line in an overnight instruction — without it you get an empty merge request every Monday whether or not there was anything to change. Anything durable — which repository is the default, how your tests are actually run, conventions the goblin should already know — belongs in [organisation memory](/en/docs/the-brain) rather than repeated in every instruction. Keep the instruction about *this* loop. ## Delivering when there is no thread to reply into An event loop replies where the event happened. A schedule loop has nowhere obvious, so the instruction names the destination: - **Post to Slack** — name a channel and the goblin posts there. - **Comment on a Linear issue** — name the issue. - **Open a merge request** — for anything that changes code, naming the repository explicitly. If the instruction names nowhere, or something went wrong along the way, the goblin emails whoever created the loop rather than failing silently. ## Each fire is independent A recurring loop produces a steady stream of reviewable changes, not a growing pile of unattended commits. Every fire opens its own merge request and is reviewed like any other. Nothing merges without you. ## Where to go next - **[Event loops](/en/docs/event-loops)** — the other trigger kind, for work your tools announce. - **[Loops](/en/docs/loop-engineering)** — the primitive both trigger kinds share. - **[Automatic top-up](/en/docs/automatic-top-up)** — keeping the credit balance from stalling unattended work overnight. # Connect your integrations Source: https://taskgoblin.ai/en/docs/connect-your-integrations TaskGoblin connects to two kinds of tools, and the distinction shapes how you sign up: - **A git provider** — **GitLab** or **GitHub** — supplies your repositories and provisions your organisation. Exactly one per organisation, chosen when you sign in. - **Capability providers** — **Linear**, **Jira**, **Slack**, and **Microsoft Teams** — add surfaces where loops can fire and goblins can report back. You connect these into an organisation you already have. Manage them all from **Integrations** in your organisation menu (`/{organisation}/integrations`). **Connecting a provider installs its default loops.** That is the practical consequence worth holding on to: an integration is not just a credential, it is a set of standing behaviours arriving with it. See [Event loops](/en/docs/event-loops) for what each one installs. ## Git providers (GitLab or GitHub) Signing in *is* connecting your git provider — one OAuth consent both authenticates you and provisions your organisation and repositories. That is why there is no separate "connect your repo" step. ### GitLab Connecting GitLab enumerates the groups you belong to and provisions a TaskGoblin organisation for each one, plus a personal organisation. The goblin posts as `@taskgoblin` on merge requests and issues. If the token ever needs refreshing, the Integrations page offers a one-click **Reconnect**. Installs: **Review merge requests**, **Work on assigned issues**. ### GitHub GitHub is a **GitHub App**, not a classic OAuth app. You install the TaskGoblin app on the organisation you want, and each installation becomes one TaskGoblin organisation. The app mints short-lived installation tokens on demand and the goblin posts as `taskgoblin[bot]`. Because permissions refresh through the installation itself, GitHub organisations never need a manual reconnect. Installs: **Review pull requests**, **Work on labelled issues**. A git-provisioned organisation is locked to the provider that created it — that provider's card offers **Reconnect** rather than Disconnect. ## Capability providers ### Linear A one-click OAuth consent into your active organisation. Once connected, goblins can pick up issues assigned to the TaskGoblin agent, read the issue and its comments for context, and post status, activity, and the merge-request link back onto the issue. Installs: **Work on assigned issues**. ### Jira An Atlassian OAuth consent, connecting your Jira site into the active organisation. Goblins pick up issues assigned to the TaskGoblin account and answer mentions on issue comments, replying as a comment on the issue and moving it through your workflow when you ask. A Jira issue rarely names a repository, so the goblin works the destination out from the request, your [organisation memory](/en/docs/the-brain), and your connected repositories — and asks rather than guessing when it genuinely cannot tell. Telling it once is enough; it writes the answer down. Installs: **Work on assigned issues**. ### Slack Connecting Slack lets anyone mention the goblin in a thread and get a reply where the conversation is happening. The bot token does not expire, so there is nothing to refresh. Slack is also where schedule loops deliver digests and reminders when the instruction names a channel. Installs no loops of its own — it is a surface, not a trigger. ### Microsoft Teams Mention the goblin in a Teams channel, a group chat, or a direct message and it replies in place, editing its own message as the work progresses. Connecting verifies your Microsoft tenant; there is no bot token for you to manage. Installs no loops of its own. ## How the goblin authenticates as itself You never paste a personal access token into TaskGoblin, and the goblin never sees your credentials. Each provider has its own bot identity — `@taskgoblin` on GitLab, Slack, and Teams, `taskgoblin[bot]` on GitHub. Inside the sandbox, git credentials are provisioned per organisation at run time (a GitLab OAuth token, or a freshly minted GitHub installation token) and injected into the environment *around* the agent rather than handed to it as something to read. That boundary is deliberate and it is also why the goblin comments through its own integrations rather than through the git token it was given: feedback posted with your token would appear under *your* name. Everything a goblin says, it says as itself. ## Disconnecting Disconnect a provider from the Integrations page and goblins lose that access immediately — the loops that depended on it stop firing, and nothing further is read or posted there. Reconnecting restores the same connection. ## Where to go next - **[Event loops](/en/docs/event-loops)** — what each provider's default loops do, and how to change them. - **[Ad-hoc runs](/en/docs/ad-hoc-runs)** — mentioning the goblin directly on any connected surface. - **[Quickstart](/en/docs/quickstart)** — the whole path from sign-in to your first loop. # Ad-hoc runs Source: https://taskgoblin.ai/en/docs/ad-hoc-runs [Loops](/en/docs/loop-engineering) cover the work that should happen whether or not anyone asks. This page covers the other half: asking directly. Ad-hoc runs are for the things that genuinely are one-offs, and for steering work already in flight — *"address the review comments"*, *"add a test for that edge case"*, *"what would it take to pull this apart?"*. Unlike loops, they are **never gated**. If a person asked, a goblin answers. ## Mention it on a merge request or pull request Leave a comment mentioning the goblin on an existing MR or PR: - On **GitLab**, `@taskgoblin` in a merge-request note. - On **GitHub**, `@taskgoblin` in a pull-request or issue comment. Use it to iterate: `@taskgoblin please address the review comments`, or `@taskgoblin add tests for the edge case in the last commit`. The goblin checks out the existing branch and pushes a follow-up commit to it — it does not open a competing branch. ## Reply to a review comment When a review loop has left inline comments, reply `@taskgoblin fix` to any one of them. That scopes a run to exactly that finding: the goblin implements it, pushes the commit, and marks the comment resolved. You are not re-litigating the whole review, just accepting one of its suggestions. ## Ask in Slack or Microsoft Teams Mention the goblin in a **Slack** thread or a **Microsoft Teams** channel, group chat, or direct message. It replies where the conversation is happening, so the answer lands in front of everyone already discussing it. Chat is the right surface when a request starts as a discussion rather than a ticket — *"is this feasible?"*, *"why does this endpoint 500 for enterprise accounts?"*. The goblin reads the thread before answering, so you do not have to summarise what everyone just said. ## Follow up on an issue On a **Linear** issue the goblin is already working, or a **Jira** issue where you mention it in a comment, just describe the change. The run resumes on the same branch with the full history of the work so far — no re-explaining, no fresh start. ## Run as many as you like at once There is no queue. Every ad-hoc run gets its own thread, branch, and cloud sandbox, so nothing steps on anything else. Hand off five at once and five goblins work in parallel, each opening its own merge request. ## What every ad-hoc run has in common - **The goblin arrives with context.** It reads the issue, the thread, the diff, and your organisation's conventions before it starts. - **Work happens in an isolated cloud sandbox**, on a dedicated branch, never on your machine. - **The result comes back where you asked** — a merge request, a review comment, or a reply in the thread. ## When an ad-hoc run wants to be a loop Ad-hoc runs are the honest measure of what your team keeps needing. Watch for the ask you type more than twice: - Mentioning the goblin on every pull request to review it → that is the **review event loop**, already installed. - Asking on Friday for a summary of the week's merges → a **schedule loop**. - Pasting the same context every time because it never remembers your conventions → that is not a loop, that is [organisation memory](/en/docs/the-brain); write it down once. The goblins can create loops themselves mid-run, so *"do this every Monday from now on"* is a perfectly good thing to say out loud in a thread. ## Where to go next - **[Event loops](/en/docs/event-loops)** — the unprompted half: reviews, assignments, labels. - **[Schedule loops](/en/docs/schedule-loops)** — recurring work on a cadence. - **[How a run works](/en/docs/how-the-agent-works)** — what happens between your mention and the merge request. # How a run works Source: https://taskgoblin.ai/en/docs/how-the-agent-works Every [loop](/en/docs/loop-engineering) turn runs the same way, whether it was fired by a webhook, a clock, or someone mentioning the goblin directly. This page is what happens between that trigger and the merge request. ## 1. The trigger lands TaskGoblin finds or creates the **thread** for that piece of work — the conversation for one issue, one merge request, one loop — and records the turn as a message in it. A follow-up on work already in flight joins the existing thread rather than starting a fresh one, which is why the goblin never asks you to re-explain. ## 2. The sandbox comes up The run gets an isolated cloud container with a checkout of your repository. Sandboxes are **persistent and reused across a thread's turns**, so a follow-up lands in an environment that already has the repository and the previous turn's state — the goblin resumes instead of starting from an empty box. Sandboxes are often pre-warmed, which is why a run usually starts working in seconds rather than waiting on a cold container. [The cloud sandbox](/en/docs/the-cloud-sandbox) covers isolation, persistence, and self-hosting in depth. ## 3. It reads before it writes Before touching code the goblin gathers context: the issue or the diff that triggered it, the thread's history, the handoff note the previous goblin left, and your [organisation's conventions](/en/docs/the-brain). For an event loop, your standing instruction is layered on top of the event's own context. This is the step that separates a useful change from a plausible one. An agent that can see how the last change was reviewed, and why an earlier approach was reverted, makes better decisions than one starting in an empty room. ## 4. A real coding agent does the work Inside the sandbox runs an actual coding agent — **Claude Code**, **Codex**, or **Gemini**, depending on the model account for the run. It has the tools a developer has: it reads and edits files, runs commands, and runs your tests. It is not autocompleting a diff, it is working the problem. ## 5. Branch, commit, push, merge request The goblin follows the workflow your team already uses: 1. It works on a **dedicated branch** — `142-taskgoblin` for issue 142 on GitLab or GitHub, `proj-123-taskgoblin` for a Jira key — never your default branch. 2. It commits, signing its work so the trail is legible, and pushes the branch. 3. It opens a **merge request** (GitLab) or **pull request** (GitHub) and reports the link back where the work started. A run triggered *on* an existing merge request is the exception: it pushes to that MR's own branch rather than opening a competing one. Because the output is a branch and a merge request, review is exactly what it already is for human contributions. Nothing merges without your say-so. ## 6. It reports where you are already looking Throughout the run the goblin talks back through the surface the work belongs to: activity on a Linear issue, inline comments on a merge request, a self-updating card in Slack or Teams. You do not watch a terminal, and there is no separate dashboard you have to remember to open. ## 7. It writes down what happened The last thing a goblin does — after the reply is sent, never before it — is record a handoff note: what it learned, what it decided, what is still open. The next turn reads that first. This is why a loop compounds instead of repeating. See [The brain](/en/docs/the-brain). ## Secrets stay out of the agent The goblin never sees your credentials. Git access inside the sandbox is provisioned per organisation at run time — a GitLab OAuth token or a freshly minted GitHub installation token — and injected into the environment *around* the agent rather than handed to it as something to read. It can *use* the access it needs to clone and push without your secrets ever entering its context or its transcript. That token is for git transport only. Comments, reviews, and issue updates go through TaskGoblin's own integrations so they post as the goblin rather than as you. ## When something goes wrong A run that fails does not disappear. The goblin reports back plainly on the surface you triggered it from, the failure is recorded on the run, and the handoff note carries the wall it hit so the next turn does not rediscover it. A run that never got a sandbox — one blocked by an empty credit balance, for instance — is never billed. ## Where to go next - **[The cloud sandbox](/en/docs/the-cloud-sandbox)** — isolation, persistence, and running on your own infrastructure. - **[The brain](/en/docs/the-brain)** — the written knowledge that carries work forward. - **[Pricing and credits](/en/docs/pricing-and-credits)** — what a turn costs, metered per second. # The cloud sandbox Source: https://taskgoblin.ai/en/docs/the-cloud-sandbox Every turn of every [loop](/en/docs/loop-engineering) runs somewhere, which makes *where does my code run?* the single most important question about TaskGoblin. It has one answer: in an isolated cloud sandbox, never on anyone's laptop. This page explains what that sandbox is, why it is isolated, and how it stays that way as your team grows. ## What the sandbox is A sandbox is an isolated container in the cloud with a checkout of your repository. When you hand off a task, the agent runs *inside* that container — it reads and edits files, runs commands, and inspects the repo there, with no access to your machine and no dependency on it being switched on. Because the sandbox lives in the cloud, the work is asynchronous by nature — and it is what lets a loop fire at 03:00 with nobody awake, or ten loops fire at once without queueing behind each other. ## Isolation: one boundary per organisation Each organisation's work runs inside its own sandbox. That boundary is the core of TaskGoblin's data isolation — one organisation can never read or write another organisation's code, repositories, or run history. The agent only ever sees the workspaces, repositories, and projects you explicitly connect; disconnect a connection and it loses access on the spot. ## Persistence: it remembers the setup, not just the task The sandbox is **persistent** and reused across a thread's messages. A follow-up on the same issue lands in an environment that already has the repository cloned and the previous run's state in place — so the agent resumes quickly instead of starting from an empty box every time. This is what makes iterating on a task feel continuous rather than repetitive. (For how that continuity carries *decisions* across runs, see [The brain](/en/docs/the-brain).) ## Secrets stay outside the agent The agent never sees your credentials. Git access inside the sandbox is provisioned per organisation at run time — a GitLab OAuth token or a freshly minted GitHub installation token — and injected into the environment *around* the agent rather than handed to it as something to read. The agent can *use* the access it needs to clone and push, without your secrets ever entering its transcript or context. This is a deliberate boundary, not a side effect: the credential is available to the git tooling in the sandbox, but it is never part of the material the agent reads or reasons over. ## Custom sandboxes You can bring a **custom sandbox** — a container image preloaded with the toolchain, system packages, and services your project needs to build and test. When the agent's work depends on more than a bare checkout (a specific runtime, a database, private build tooling), a custom sandbox means the environment is ready the moment a task starts, and the agent's changes can be verified in a realistic setup. ## Self-hosted sandboxes Teams with compliance or data-residency requirements can run sandboxes on **their own infrastructure**. The control plane still schedules and drives the work, but the container where your code is checked out and executed lives inside your environment — so source, build artifacts, and run state never leave a boundary you control. This is the option to reach for when "in the cloud" needs to mean *your* cloud, and it is also the cheapest way to run: $0.10 a minute, paired with your own LLM account. See [Bring your own sandbox server](/en/docs/bring-your-own-sandbox-server) for how to register one — and why platform model credentials are never placed on infrastructure you control. ## Where to go next - **[How a run works](/en/docs/how-the-agent-works)** — the full trigger-to-merge-request flow inside a single turn. - **[Loops](/en/docs/loop-engineering)** — the primitive every sandbox run serves. - **[Bring your own sandbox server](/en/docs/bring-your-own-sandbox-server)** — running goblins on your own infrastructure, and what it costs. - **[Schedule loops](/en/docs/schedule-loops)** — unattended runs using the same sandbox model on a cadence. # The brain Source: https://taskgoblin.ai/en/docs/the-brain Every TaskGoblin run is a fresh goblin. There is no long-lived session holding your context, and often not even the same model account between one turn and the next. That sounds like a weakness until you look at what it forces: **nothing is remembered by accident.** Anything that matters between runs has to be written down — which means you can read it, correct it, and rely on it. The place it gets written down is the **brain**: your organisation's own body of written knowledge, kept as markdown pages that both you and your goblins can read, search and edit. Everything else on this page is a consequence of that one decision. ## One brain, made of pages A brain is a set of pages. Each has an **address** — `conventions/testing`, `people/alice`, `runbooks/rollback` — a title, some markdown, and any tags you give it. Addresses are paths, so they read like files, and TaskGoblin shows them that way: `/conventions/testing.md` is a page, `/conventions` is a folder. That is also the URL, so a page can be linked into a chat, a merge request or a ticket the same way you would link anything else. Folders are worth one sentence of explanation, because they are not what they look like. **There is no such thing as creating a folder.** A folder is just an address prefix that more than one page happens to share: write `runbooks/rollback` and `runbooks/incident` and you have a `runbooks` folder; move the last page out of it and it stops existing. Nothing to set up, nothing to clean up. ## The two addresses that already exist Two parts of the brain are written by goblins whether or not anyone ever opens the section. **`memory` — the playbook.** One page, read by every goblin on every thread before it starts work. This is where the durable, organisation-wide facts live: which repository is the default, how the test suite is actually run, that migrations are never edited after the fact, that this team writes merge-request descriptions in a particular shape. It is how *"correct it once and every goblin after it gets it right"* actually works. Goblins write to it themselves when they learn something durable — tell one which repository to use for a repo-less Jira ticket and it records the answer rather than asking again next week. You can also just say it: *"remember that we run the suite with `make test`, not `npm test`"*. And you can open the page and edit it like any other. **`tasks/…` — a page per piece of work.** Each thread — one issue, one merge request, one loop — gets its own page under `tasks/`. At the end of a shift the goblin writes what it learned, what it decided, what it deliberately did not do, and what it hit a wall on. When the next turn fires, that page is the first thing the next goblin reads, alongside the branch its predecessor already pushed. These are written on **every** shift, including the ones that achieved nothing. A goblin that spent its run blocked on a missing credential records that, so the next one does not spend its run rediscovering the same wall. The practical effect is the one you feel first: come back three days later with *"actually, can we do it the other way?"* and the run resumes with the history in hand. Nobody pastes context back in, because the context lives with the work rather than in someone's chat window. ### Why a task page is an ordinary page `tasks/` is a normal, visible, searchable folder — not a hidden compartment. That is the whole upgrade over a note stapled to one row in a database: **what one task learned is findable from every other task.** Six weeks ago a goblin worked out that your staging deploy needs an extra migration step, and wrote it into that ticket's page. Today a different goblin, on an unrelated ticket, searches before it starts and finds it. Nobody had to promote that note anywhere, and nobody had to remember it existed. ## Pages that link themselves Refer to another page by its address in a sentence — *"see conventions/testing before changing the suite"* — and the two pages link. Write it as `[[conventions/testing]]` and it renders as a link as well. You do not maintain the reverse direction. Every page shows a **Linked from** panel listing what points at it, with the sentence each reference sits in — so before you change a page you can see who is relying on it. Refer to a page that does not exist yet and the link renders as missing, pointing at a create form with the address already filled in; write the page later and every reference to it lights up. This is the part that makes a brain accumulate rather than sprawl. A folder of unrelated documents gets harder to use as it grows. A graph of documents that cite each other gets easier, because the way in is any page adjacent to what you were already reading. ## What belongs where | Put it in the **task** page | Put it in **`memory`** | | --- | --- | | What this branch already changed | Which repository is the default | | An approach that was tried and reverted | The command that actually runs the tests | | A decision waiting on a reviewer's answer | Conventions: branch names, commit style, MR descriptions | | A wall hit on this specific ticket | Standing preferences: "never touch generated files" | The dividing line is simple: if it stops being true when this ticket closes, it belongs on the task page. Everything else — architecture notes, runbooks, the reasoning behind a decision nobody remembers making, notes on who owns what — is just a page you write at an address that makes sense. The brain is not limited to the two reserved addresses; those are only the two that fill themselves in. ## Conventions beat instructions The brain exists so your [loop instructions](/en/docs/loop-engineering) can stay short. An instruction that has to re-explain your repository layout, your test command and your review conventions on every single run is one you will stop maintaining. Push the durable parts into the brain and the instruction shrinks to the part that is actually about *this* loop. This is also the fastest fix when a loop starts producing work you do not like. Before rewriting the instruction, ask whether the goblin is missing a **fact** — a convention nobody ever wrote down. Recording it once fixes every loop at the same time. ## Where memory does not go The brain is written by goblins and readable by you. Credentials are not part of it: tokens are injected into the environment *around* the agent at run time and never enter what it reads or writes. A goblin cannot record a secret in a task page because it never had one to record. See [The cloud sandbox](/en/docs/the-cloud-sandbox) for how that boundary is drawn. Each organisation's brain is its own. It is never shared, never pooled, and never read by a run belonging to anyone else. ## Where to go next - **[Writing and organising the brain](/en/docs/writing-and-organising-the-brain)** — writing pages, importing what you already have, and keeping it tidy as it grows. - **[How a run works](/en/docs/how-the-agent-works)** — where the brain is read and written inside a single turn. - **[Loops](/en/docs/loop-engineering)** — why written continuity is what makes a loop compound rather than repeat. - **[The cloud sandbox](/en/docs/the-cloud-sandbox)** — the other half of continuity: an environment that survives between turns. # Writing and organising the brain Source: https://taskgoblin.ai/en/docs/writing-and-organising-the-brain [The brain](/en/docs/the-brain) fills itself in as goblins work, but the pages *you* write are the ones that change what they do. This page is the practical half: getting knowledge in, keeping it findable, and rearranging it without breaking anything. ## Writing a page A page is an address, an optional title, and markdown. The editor shows your text beside a live preview, which is rendered by the same pipeline the published page uses — so what you are looking at while you write is what the page will be. Tags are optional and flat: `docs`, `runbook`, `security`. They cut across folders, which is what makes them worth having — a tag collects pages that live in different places, where a folder collects pages that live in the same one. One thing worth knowing: **saving replaces a page's tags with whatever the editor submits.** The tag control exists so that a save always states them, rather than a content edit quietly clearing them. ## Choosing an address Addresses are lowercase letters, numbers and dashes, in segments separated by `/`. `conventions/testing`, `people/alice`, `runbooks/rollback`. The address is the page's identity, so it is worth ten seconds of thought: - **Name the thing, not the moment.** `runbooks/rollback` still makes sense next year; `notes/tuesday-meeting` does not. - **Group by how you will look for it**, not by who wrote it. `deploys/staging` beats `alice/deploy-notes`. - **Shallow beats deep.** Two levels is almost always enough. A brain is browsed by searching and by following links, not by clicking down a tree. - **It is what gets referred to.** A goblin writing *"see conventions/testing"* in a sentence creates a link, so an address that reads naturally in prose is an address that gets cited. Addresses can be changed later, and changing one repairs the references — see below. ## Bringing what you already have If your conventions currently live in a `docs/` folder, a wiki export, or a pile of READMEs, import them rather than retyping them. Drop the files or the folder onto the import area and TaskGoblin shows you what each one **would** become — its address, its title, and whether something already lives there — before anything is written. Conflicts are decided per file, by you, because nobody can resolve a conflict they were not shown. Some details that save a surprise: - **Folder structure survives.** `docs/people/Alice Chen.md` becomes `people/alice-chen`; the directory layout turns into address prefixes. - **Non-markdown files are ignored**, and the count of what was skipped is shown. A real docs folder with 40 markdown files beside 300 screenshots imports the 40 and tells you it left 300. - **A batch is up to 200 files and 20 MB**, all or nothing. Import a big archive in a few passes. - **The import lands in the folder you are standing in.** Open `runbooks` first and the whole batch arrives underneath it. Going the other way, **Export** hands you a ZIP of the entire brain as markdown files, with the folder structure mirroring the addresses. It is there so the answer to *"can we get our knowledge back out?"* is a button rather than a conversation. ## Rearranging without breaking things Pages can be moved, folders renamed, and either deleted — one at a time from the row menu, or several at once by selecting them. **Moving repairs the links.** When a page changes address, every `[[wikilink]]` pointing at it on every other page is rewritten to the new one. Without that, moving a well-cited page would quietly turn a dozen good references into broken ones. Sentences that merely mention the old address in prose are deliberately left alone — those are someone's writing, not markup, and rewriting them would be editing prose you did not ask anyone to edit. **Renaming a folder is all or nothing.** If one page in it cannot move — something already occupies the destination — nothing moves. Half a rename leaves a folder existing under two names with no way to tell which pages were meant to be where. Moving a *selection*, by contrast, is per page: one awkward member of a hand-picked set of forty should not lose you the other thirty-nine. **Two addresses cannot move**: `memory`, because that is where the organisation playbook is written, and anything under `tasks/`, because each of those pages is pointed at by the thread it belongs to. Everything else is yours to arrange. ## Deleting, and getting it back Deleting is a soft delete. The page leaves the tree, the search results and the goblins' tools straight away, and stays recoverable from **Recently deleted for 72 hours** — after which it is removed for good. A bulk delete offers **Undo** immediately, which matters more than it sounds: deleting a folder resolves server-side, so your browser never knew which forty pages went. Recently deleted is there for the slower change of mind. Goblins can delete pages, but they cannot restore them. That is deliberate. Restoring is a judgement about whether a deletion was *right*, and an agent that could undo its own deletions could undo yours. ## Finding things Search is the same ranking your goblins get — meaning as well as words, so a page can match a question it does not share any vocabulary with. That parity is on purpose: an agent citing the third-best page while the person beside it reads the first is a disagreement neither of them can resolve. You can also filter by tag, or browse the folder tree, and any folder or page you land on has its own address you can share. ## Letting a goblin tidy up Two kinds of maintenance keep a brain healthy, and TaskGoblin separates them. The mechanical half — keeping search indexes current, deriving links, clearing out pages past their recovery window — runs on a schedule, costs nothing, and needs no decision from you. Correctness should not depend on anyone having credit. The other half is judgement: merging two pages that have drifted into covering the same thing, rewriting a page the code has since contradicted, retiring one that has been superseded. That is real work by a real goblin, so it ships as a loop — **Tidy the brain**, which runs daily at 03:00 once you enable it — and it ships **paused**. It is an ordinary billed run, and deciding that something you wrote should be merged or retired is not a decision to make on your behalf without asking. If you turn it on, it is deliberately conservative: it will not delete a page merely for being old, and when two pages disagree and it cannot tell which is right, it leaves both and writes down that they disagree. Anything it does retire is restorable for 72 hours like any other deletion, and it reports what it merged, rewrote and retired when it finishes. ## Where to go next - **[The brain](/en/docs/the-brain)** — what the brain is, and the two addresses that fill themselves in. - **[Loops](/en/docs/loop-engineering)** — the primitive "Tidy the brain" is built on, and how to enable it. - **[How a run works](/en/docs/how-the-agent-works)** — where the brain is read and written inside a single turn. - **[Schedule loops](/en/docs/schedule-loops)** — unattended runs on a cadence, of which brain consolidation is one. # Pricing and credits Source: https://taskgoblin.ai/en/docs/pricing-and-credits TaskGoblin has one billing relationship: you buy **credits**, and runs spend them. There are no plans, no seats, no monthly fee, and nothing to upgrade or downgrade. The promise is forecastability — you pay for the seconds a goblin actually works, at a rate you already know. ## Pay for time, not tokens Most AI tools bill against a moving target: model tier, token count, tool calls, context size. You cannot predict any of those before the work happens, which means you cannot predict the bill either. TaskGoblin bills **time**. A run is metered per second, from the moment the agent starts working to the moment it stops, and charged at a flat per-minute rate. At the standard rate, $0.40 a minute is about $24 an hour — a fraction of an engineer, except goblins run in parallel, overnight, and on demand. ## The three rates The rate for a run depends on whose LLM account and whose infrastructure it used: | What you bring | Rate | | --- | --- | | Nothing — our LLM account, our sandboxes | **$0.40** / minute | | Your own LLM account | **$0.20** / minute | | Your own LLM account **and** your own sandbox server | **$0.10** / minute | The rate is decided once, when the run starts, from the resources it was actually given — and it is recorded on the run, so a later price change never rewrites what you were charged. There is deliberately **no rate for bringing only your own infrastructure**. See [Bring your own sandbox server](/en/docs/bring-your-own-sandbox-server) for why: TaskGoblin never injects its own provider credentials into infrastructure a customer controls, so a run on your server always uses your LLM account. ## What counts as working time Only the agent's active working time is billed: - **Billed** — the agent reading the repository, planning, editing files, running commands and tests, and reporting back. - **Not billed** — time a task spends queued, time a sandbox sits idle between runs, and the time you spend reading the result or writing a follow-up. Metering is per second with **no per-run minimum** and no rounding up to the next minute: a 90-second run costs 90 seconds. A run that fails or is stopped by the watchdog is billed for the time it used before it stopped — failed work still consumed real compute — and never for more than that. ## Your first $100 is on us Every new organisation is granted **$100 in evaluation credits**, once, with no card on file. That is around four hours of agent time — enough to connect a repository, hand over real tasks, and judge the output before spending anything. ## Topping up Credits are bought as one-off card payments from your organisation's billing page, in whatever amount suits you. They do not expire and there is no monthly reset, so buying ahead costs you nothing. If you would rather never think about it, turn on [automatic top-up](/en/docs/automatic-top-up) — it is available on every organisation and switched **off** by default. ## When the balance runs out A run already underway finishes; the balance may dip below zero rather than a goblin abandoning work halfway. New runs are then held until credits land, and the block lifts on its own the moment they do — nothing to re-enable, no support ticket. ## Where to go next - **[Bring your own LLM account](/en/docs/bring-your-own-llm-account)** — drop to $0.20 a minute by using your own provider account. - **[Bring your own sandbox server](/en/docs/bring-your-own-sandbox-server)** — the $0.10 rate, and the security rule behind it. - **[Automatic top-up](/en/docs/automatic-top-up)** — keep the balance from ever reaching zero. # Bring your own LLM account Source: https://taskgoblin.ai/en/docs/bring-your-own-llm-account If your team already pays a model provider, you can point TaskGoblin at that account instead of ours. The platform behaves exactly the same — same goblins, same cloud sandboxes, same integrations — but the model spend goes to your provider and your rate drops from $0.40 to **$0.20 a minute**. ## Adding an account An organisation Owner or Admin adds LLM accounts in the organisation's settings. You provide the provider and its credential — an API key, or the authentication a provider subscription uses — and the account becomes available to that organisation's runs immediately. A few properties are worth stating plainly: - **The account belongs to one organisation.** It is never shared with, visible to, or selectable by any other organisation on the platform. - **Credentials are encrypted at rest** and are never sent back to your browser after saving. Editing an account shows you that a credential is set, not what it is. - **Removing an account** stops it being chosen for new runs while keeping the history of the runs that used it, so past charges stay explainable. Members who are not an Owner or Admin cannot see or manage these accounts. ## How a run picks an account When a run starts, TaskGoblin prefers your organisation's own LLM account whenever it is usable — active, healthy, and not rate-limited by the provider. That single decision fixes the run's rate at $0.20 a minute (or $0.10 if the run also lands on [your own sandbox server](/en/docs/bring-your-own-sandbox-server)). If your account is unavailable — the key was revoked, the provider is rate-limiting you, the account was removed — the run does not fail. It falls back to a TaskGoblin account and is billed at the standard $0.40 rate. The choice is made once per run and recorded on it, so a run never changes rate halfway through. ## What you still pay us for The per-minute rate covers the platform: the sandbox your code runs in, the integrations, the scheduling, the review loop, the run history, and the support behind them. What it no longer covers, on this rate, is the model usage itself — that lands on your provider's bill, under your own quota, spend controls, and data-processing agreement. That last part is the reason many teams choose this path: model traffic runs under the contract their organisation already reviewed. ## Where to go next - **[Pricing and credits](/en/docs/pricing-and-credits)** — how metering and the three rates work. - **[Bring your own sandbox server](/en/docs/bring-your-own-sandbox-server)** — pair this with your own infrastructure for $0.10 a minute. - **[The cloud sandbox](/en/docs/the-cloud-sandbox)** — where runs execute, and how credentials stay outside the agent. # Bring your own sandbox server Source: https://taskgoblin.ai/en/docs/bring-your-own-sandbox-server You can register your own sandbox server and have goblins do their work inside your environment — your machines, your network, your boundary. Combined with [your own LLM account](/en/docs/bring-your-own-llm-account), that is the lowest rate we offer: **$0.10 a minute**. ## Registering a server An organisation Owner or Admin registers a sandbox server in the organisation's settings with its URL and API key. The key is encrypted at rest, the server joins the same health-check schedule as our own fleet, and it becomes available to that organisation's runs — and to no one else's. - **The server belongs to one organisation.** Containers on it are only ever claimable by that organisation; no other tenant can be scheduled onto it. - **Health is checked continuously.** If your server is unhealthy or at capacity, runs fall back to TaskGoblin infrastructure rather than queueing behind it — never to another customer's server. - **Removing a server** stops new work being placed on it and stops its containers being claimed. The control plane still schedules the work, drives the agent, and records the run history. What moves to your side is the container where your code is checked out and executed — so source, build artifacts, and run state stay inside a boundary you operate. ## Why there is no infrastructure-only rate This is the part worth reading twice, because it is a security guarantee before it is a pricing rule. **TaskGoblin will never inject its own provider credentials into infrastructure a customer controls.** A platform LLM key placed on a machine we do not operate is a key we can no longer protect: we cannot guarantee who can read the environment, inspect the process, or capture traffic on hardware that is not ours. So we simply do not do it — not for a large customer, not for a trusted one, not as an exception. The consequence is the pairing rule: - Your LLM account **and** your server → the run executes on your infrastructure with your credentials, at $0.10 a minute. - Your server, but no usable LLM account of your own → the run needs one of *our* provider accounts, so it stays on *our* infrastructure at $0.40 a minute. Your server is simply unused for that run. There is no "bring only your own infrastructure" discount, because there is no arrangement in which we would put our credentials there. If your own LLM account becomes unavailable mid-thread, the next run falls back to our account *and* our infrastructure together — the pairing holds for every run individually. ## What this is good for Teams reach for their own sandbox server when "in the cloud" has to mean *their* cloud: data-residency requirements, private networks and internal package registries the agent must reach, compliance regimes that require execution inside an audited environment, or simply spare capacity they would rather use than rent. ## Where to go next - **[Bring your own LLM account](/en/docs/bring-your-own-llm-account)** — the other half of the $0.10 rate. - **[Pricing and credits](/en/docs/pricing-and-credits)** — metering, rates, and how a run's rate is fixed. - **[The cloud sandbox](/en/docs/the-cloud-sandbox)** — what a sandbox is, and how secrets stay outside the agent. # Automatic top-up Source: https://taskgoblin.ai/en/docs/automatic-top-up Credits only matter when they run out at the wrong moment — an overnight loop that stops halfway, a review that never posts. Automatic top-up exists to make that impossible without handing us a blank cheque. It is available to every organisation and it is **off by default**. Nothing is ever charged automatically until an Owner or Admin turns it on. ## Turning it on From the organisation's billing page, an Owner or Admin: 1. Saves a card (stored by our payment provider, never by us). 2. Chooses a **threshold** — the balance at which a refill should trigger. 3. Chooses an **amount** — how much to buy each time it triggers. A sensible starting point is a threshold covering a day or two of your usual agent time, and an amount covering a few weeks. Both are editable at any time, and switching automatic top-up back off stops all further automatic charges immediately. ## How a refill happens The balance is checked after each run is charged. If it has fallen below your threshold, TaskGoblin charges the saved card for your configured amount and the credits appear on the balance with an entry in your billing history, exactly like a manual purchase. Two behaviours are worth knowing: - **One refill at a time.** Many goblins can be working in parallel, and several of them can push the balance below the threshold in the same moment. Only one top-up is ever in flight — concurrent runs cannot stampede your card. - **A declined card does not loop.** If the charge fails, the failure is recorded and surfaced on the billing page, and no retry storm follows. The organisation falls back to the normal behaviour at zero balance: work already underway finishes, new runs wait until you top up manually or fix the card. ## Do I need it? No. Manual top-ups are perfectly workable, credits never expire, and there is no discount attached to automating it. Turn it on when unattended work — scheduled loops, automatic reviews, overnight triage — is doing enough for you that a stalled queue would be noticed the next morning. ## Where to go next - **[Pricing and credits](/en/docs/pricing-and-credits)** — what a run costs and how the balance is spent. - **[Schedule loops](/en/docs/schedule-loops)** — the unattended runs that benefit most from a balance that refills itself.