bandicot
Bandicot Docs
Chapter IStart · Available now

How-to guides

Step-by-step Bandicot guides: first task, undo a run, nightly automation, secrets, Chrome, a second Mac, teams, sharing, Agent Macs and company rollout.

Available now. A current user-facing path exists within the stated scope.

Connect a model and run your first task

Connect one provider, open a folder, type a task in the prompt bar and read the cost of the run when it ends.

You need Bandicot installed (see Install) and either an account with a model provider or a local model. This guide uses a provider key. For a model that runs on your Mac, see Local models.

Everything the agent does is saved on your Mac, and each tool call is one row you can open.

  1. Open Home with a double tap of ⌘, then choose Account › AI Gateway and stay on Providers.
  2. Find your provider's tile, paste the key and press Connect, or press its sign-in button such as Sign in with ChatGPT.
  3. When the tile reads Connected or Signed in, press Use beside one of its models.
  4. Choose File › Open Project (⌘O) and pick a folder you can afford to experiment in.
  5. Type the task in the box that says Ask Bandicot and press Enter. For example: Summarize every file in this folder in a file called notes.md.
  6. Watch the rows. Open one to see what ran. If a card says Needs your call, read it and choose Allow once or Deny.
  7. Press ⌘1 to open the Context page and read Agent cost and This turn.

If it goes wrong

The prompt bar says Connect a provider to send · /connect.
Nothing is connected yet. Type /connect, or finish the connection on the Providers tab.
The tile says Needs attention.
Read the message on the tile and press Retry, Sign in again or Replace key. See When connecting fails.

Plan a big change and let subagents do the parts

Ask for a plan, edit its steps, then let the agent start subagents for the parts and watch them in the Agents view.

A plan is the list of steps the agent works through, and you can add, edit, reorder or drop steps yourself. /plan researches first and writes the plan without starting the work. A subagent is another agent your agent starts for one piece of work, and it shows under its parent in the sidebar.

  1. In the prompt bar, type /plan followed by the change you want, and press Enter.
  2. Open the Plan pane from the View menu and read the steps. Add a step in Add a step…, or drop one you do not want.
  3. Tell the agent to start. When it offers a subagent, read the brief on the card and choose Start.
  4. Open View › Agents to see each helper's task, status and an Activity button for its live log.
  5. Line up more work with New plan under the steps. A queued plan waits until the plan above it is finished.

If it goes wrong

The Plan pane says nothing is planned.
Add a step in the pane, or ask for a plan with /plan.

Set up a project with Versions and undo an agent run

Turn on Versions for the folder before the first run, and any run can later be put back with Undo this run.

Versions saves a version of each file in the folder every time it changes, on your Mac. Agents keep working in a folder without Versions, but their changes are not recorded there, so turn it on first. Versions can only put back files in the folder: shell commands, web requests and files written elsewhere cannot be reversed, and the undo check lists them under Undo cannot take these back.

  1. Choose New project and give it a Project name, or open an existing folder with File › Open Project.
  2. Open Home › Versions with the project open, and wait while Bandicot looks at the folder. Nothing is copied yet.
  3. Read the counts for Kept, Left out by rule and Cannot be kept, then choose Start keeping versions.
  4. Ask the agent to do the work and let the run finish.
  5. Open the Saved versions page, select the run on the history line and choose Undo this run.
  6. In the check, untick any file you want to leave alone. For a file you edited after the run, choose Keep current, Take pre-run or Keep both.
  7. Choose Undo the run. The undo is a new version, so you can undo it too.

If it goes wrong

The page reads Versions is off for this folder.
Choose Review and start, then Start keeping versions.
Your home folder is not kept.
Versions does not keep the history of your home folder because it holds Bandicot's own data. Open a folder inside it.

Run a nightly automation and read its report

Create an automaton, add a schedule that repeats every twenty-four hours, keep the Mac awake and read Last report in the morning.

An automaton is an agent of your own with a name, a job and a model. It hands the real work to your agents and writes a report. A schedule repeats at an interval you set in whole minutes, so a run every twenty-four hours is 1440.

Runs that work in their own copy of the folder, such as scheduled automations, leave their changes on the Versions Review page until you apply or discard them. See Review changes from automations.

  1. Open Home › Team, then Automatons, and choose New automaton.
  2. Type a Name, such as Nightly check, and a Job that says what to look at and what to do. Choose Create automaton.
  3. Under Schedules, choose Add schedule. Write the Message each run sends, set Every (minutes) to 1440, and leave Stop after (runs) at 0 to keep it running.
  4. Under Missed runs, choose Skip them or Catch up, then Add schedule.
  5. In the Always on card of the Automatons tab, turn on Keep working when Bandicot is closed.
  6. In the morning, open the automaton. Last report reads Done, Nothing to do, Blocked or Needs you.
  7. Choose a dot under Runs to see what that run reported, and Open conversation for the full run.

If it goes wrong

Nothing ran overnight.
A Mac that sleeps runs the schedule when it wakes. Keep it awake with the controls in the Always on card, or let a second Mac cover it. See Always on.
A run reads Needs you.
Open the automaton. A card above the message box asks for an answer or a permission. An ask that nobody answers is denied.

Give an agent a password or key safely

Share the value with Share a secret or keep it in the Passwords vault, and the agent gets a note that it exists, never the value.

A pasted key goes into the transcript and to the model provider, so do not type it into a prompt. When you share a secret, the agent gets a private file and a note naming it. The value does not reach the model, the logs or the events you see, and a message that holds a secret is never sent to someone else's Mac.

  1. In the prompt bar, open the attach menu and choose Share a secret.
  2. Type or paste the value and give it a Name (optional).
  3. Choose Save securely, then send your message. The agent can read the secret only inside a command, for twenty-four hours.
  4. For a login the agent should be able to use, open Settings › Passwords and add the sign-in. An agent can have it typed where you allow, and never sees the password.
  5. When you are finished, choose Forget on a Kept secret, or Delete and then Delete for good on a vault entry.

If it goes wrong

A card headed Asking for a secret appears.
The agent needs a key it does not have. Fill the field and choose Save securely, or choose Decline.

Connect your own Chrome for a logged-in site

Install the Bandicot extension, choose Connect Chrome in Settings, and lend the one tab where you are already signed in.

The agent works only in tabs you lend it and tabs it opens itself, and the rest of your browser stays yours. It never types a password: when a page needs one it stops, the tab shows a blue edge and a Bandicot needs you card, and you type it yourself.

  1. Install the Bandicot extension in Chrome.
  2. In Bandicot, open Settings › Computer and find the Browser card.
  3. Choose Your Chrome, then Connect Chrome, and check that the dot reads Chrome connected.
  4. Open the page in Chrome and sign in if it asks.
  5. Click the Bandicot button in the Chrome toolbar. The badge shows ON.
  6. Tell the agent what to do in that page.
  7. Click the toolbar button again to take the tab back.

Pair a second Mac and answer an approval from it

Pair the Macs with a link and six matching digits, then answer an agent's permission card from whichever Mac is in your hand.

The first Mac holds your account key and is the only one that can pair, remove or make a recovery kit. The pairing link works once and counts down, so do the steps together.

  1. On the Mac you use most, open Team › Your Macs and press Start with this Mac. This Mac is now tagged Holds the key.
  2. On the same Mac, press Pair a Mac. The card shows a pairing link, six digits and a countdown.
  3. On the new Mac, open Team › Your Macs, choose Pair with a Mac you already use and paste the link into Pairing link.
  4. Check that both screens show the same six digits, then press The digits match, pair.
  5. On the Mac whose agents will ask, check that Answer this Mac's requests from my other Macs is on.
  6. When an agent there asks for permission, open Team › Your Macs on the other Mac. The ask shows under Your other Macs. Press Allow once or Deny.

If it goes wrong

The digits do not match.
Do not pair. Start again from Pair a Mac, and make sure you copied the link from your own Mac.
A long command shows only Deny.
A command too long to show in full can only be denied from the other Mac. Answer it on the Mac where it runs.

Start a team and invite someone

Start a team with a name, create an invite link for one person, send it privately and keep your Mac open until they join.

You become the owner and the coordinator of the team. The coordinator's Mac is the one that admits new people, so it must be open and signed in when someone joins.

  1. Open Home with a double tap of ⌘ and choose Team.
  2. Under Start a team, type a name in Team name and press Start team. The team starts with #general.
  3. Under Invite as, pick Member, Guest or Admin, then press Create invite link.
  4. Copy the link and send it to one person, privately. A link works once.
  5. Keep Bandicot open until they have joined. They paste it into Invite link under Join a team and press Join team.
  6. Type in Message #general and press Enter. The label under your message says where it has reached.

If it goes wrong

The invite section is missing.
Only the coordinator's Mac creates invites. Open Team on that Mac.

Lend a model to a friend

Make them a friend, switch on the model you will lend with a daily cap, and their agents use it on your key.

Only API keys and models on your Mac can be lent. A plan sign-in stays yours. Only the model call runs on your side: their tools, files and history stay on their Mac, and your key never leaves yours.

  1. Open Team › Friends, press Copy my friend link and send it to one person, privately.
  2. They paste it into Friend link under Accept their link and press Accept.
  3. Open Settings › Computer and find Lent models.
  4. Switch on the Lend to switch beside the friend, then switch on the Lend switch beside each model you are willing to lend.
  5. Pick Daily lent tokens, and watch the Lent today bar and Who borrowed today.
  6. Your friend sees the model under Lent to you, presses Use and reads New agents use that model.
  7. To stop, switch the model or the friend off, or press Stop all guest work.

Share a folder with a teammate or a friend

Open the folder in Versions, tick who gets it, choose Private or Public and press Share with.

Sharing sends every saved version of the folder over Team's encrypted link and brings their edits back. When the same lines changed on both sides, the file waits under Changed on both sides and your copy stays until you choose.

  1. Open the folder as a project and turn on Versions if it is off.
  2. Open Versions › Team.
  3. Under Share this folder, tick the teams and friends who should get it.
  4. Choose Private to offer it only to them, or Public to offer it to everyone in every team you are in.
  5. Choose Share with and the name. For one friend with no team, choose Share by link and send the link.
  6. The other person opens Versions › Team and chooses Clone under Shared with you for a new folder, or Sync into this folder for the folder they have open.
  7. When a file changed on both sides, choose Keep mine, Take theirs or Keep both.

Set up Agent Macs

Build the template Mac once in Settings, finish its checklist, and every Agent Mac is copied from it.

An Agent Mac is a virtual Mac that runs inside your Mac, so an agent can open apps, click and type on a screen of its own while your windows stay untouched. It takes memory and disk, which the Resources card shows as bars.

  1. Open Settings › Computer and choose Set up on the Agent machine card.
  2. Wait for the download and install. When the card reads The template Mac is waiting for you, choose Open the Mac.
  3. In its window, work down the checklist: Finish macOS setup and sign in, Open BandicotGuest.app from the shared folder, Allow Screen Recording and Accessibility, and Turn off FileVault, then turn on automatic login.
  4. Optionally add apps or a setup script on the Starter kit card, and Sign in once on the template.
  5. Choose Finish setup.
  6. Pick a Resource mode: Light, Balanced or Full.
  7. Turn on Agents can use it, and Automatons work on it if automations should use one.
  8. Choose Show to watch the Agent Mac's screen live.

Roll Bandicot out to a company

Start the company on the website, set the rules, invite people and hand IT the Mac profile and the download.

Pick Business. It includes 5 people, and the company page shows the exact amount before you pay. The person who starts it is the owner.

  1. Sign in on the website and open the company page.
  2. Choose the plan, the number of people and Yearly or Monthly billing.
  3. Fill in the company name, your name and your role, and tick the agreement. Press Sign and pay and finish on the Stripe page.
  4. Open the Setup tab and work through the checklist: verify your domain, choose rules, invite people.
  5. On the Rules tab, set what every Mac follows, such as Stay in the project folder or Always ask before acting.
  6. On the People tab, type an email, choose a role and press Send invite.
  7. On the Install tab, press Copy to get the link for people, and Download Mac profile to upload to your MDM. Add the Bandicot app from the download page to the same MDM group.

Save cost with a local model and the usage pane

Read where the tokens go, move small jobs to a model on your Mac, and set an allowance for the work Bandicot does on its own.

A model on your Mac costs nothing per ask, and small models are not a match for frontier models, so keep the hard tasks on a hosted model. Cost figures are estimates, not invoices, and your provider's bill is the source of truth.

  1. Press ⌘1 and read Agent stats on the Context page: Agent cost, This turn and Tokens processed.
  2. Press ⌘8 to open Efficiency and read what the agent spent on Overview.
  3. Open Home, then Account › AI Gateway › Usage, and read spend by profile over seven, thirty or ninety days.
  4. Press ⇧⌘M, pick a model under Best for this Mac and press Download & use.
  5. Under AI Gateway › Decisions, press the name of a Laya model so quick questions cost nothing per ask.
  6. In Usage, type an amount in Automatic AI allowance · USD and press Save account limit.
  7. On an Anthropic or OpenAI API key, turn on Slow lane for automations to run automation work at half price. It can take hours.

Move to a new Mac with the recovery kit

Make a recovery kit and a second copy on the old Mac, then restore the copy on the new one with the kit.

Bandicot does not keep your recovery words and cannot show them again, so write them down and keep them somewhere safe. Without the kit nothing in the copy can be read.

  1. On the Mac that holds the key, open Team › Your Macs and press Make a recovery kit. Copy the Recovery words and the Recovery envelope and store them safely.
  2. Open Versions › Backups, choose Type your recovery kit, type it twice, and choose Start copies.
  3. Answer Keep a copy for iCloud Drive or for a disk you plug in, and say yes when macOS asks once about iCloud Drive.
  4. On the new Mac, turn on iCloud Drive with the same Apple Account, or plug in the disk.
  5. Open Versions › Backups › Restore your Bandicot history and choose Look for copies.
  6. Type your recovery kit and choose Open this copy.
  7. For each project, choose Choose folder and pick an empty folder, or leave it out. Choose Restore.
  8. Quit and reopen Bandicot to load the restored agents and settings.

If it goes wrong

You lost the Mac that held the key.
On a new Mac, open Team › Your Macs, press Restore from a recovery kit, enter the Recovery words and paste the Recovery envelope.

Questions

Which guide should I read first?

Read the first one, which connects a model and runs a first task. Then turn on Versions on the same project, because that makes every later guide safer.

Are the button names exact?

They are the labels the app shows, in backticks. If a label on your screen differs, the app is newer than this page, so check the Troubleshooting page and the page for that feature.

Do these guides work on the Free plan?

Yes, except the ones that need a company or more profiles. Free has every capability of the app for one profile, and the company guide needs Business.

Where do I find what each setting does?

Every setting is explained on the Settings page, in the order the app shows them. Shortcuts are on Keyboard shortcuts.