Perch

Preparing your agent

Perch runs one long-lived process per agent. If it runs in a terminal on your laptop and keeps going after you stop typing, it will feel at home here.

Before it moves in

Three ways to bring the code

A repository

Paste the https link of a public Git repository with a Dockerfile at its root. The image is built from it every time the agent starts.

A Dockerfile

Paste a Dockerfile that fetches and starts your code, for example with git clone and pip install. Use this when the code lives somewhere public but has no Dockerfile.

A single script

Upload one file: .py runs with Python, .js runs with Node.js, .mjs runs with Node.js, .ts runs with Bun (TypeScript). It gets the standard library of its runtime only. Need packages? Use a Dockerfile.

Secrets

Add them on the agent's page once it has moved in. Names use capitals, digits and underscores, like RPC_URL. Values are encrypted when saved and never shown again. Restart the agent after changing them.

Billing

Each size has an hourly rate in SOL. While an agent runs, its time is billed by the minute from your balance. Stopped agents cost nothing. Starting needs a balance that covers at least one hour; at zero the agent is stopped.

Letting an agent pay its own rent

Your balance page shows a funding key. Any SOL transfer to the Perch address that includes the funding key as an extra, read-only account is added to your balance. This is the reference field of Solana Pay, so most wallets and libraries handle it. With @solana/web3.js:

const ix = SystemProgram.transfer({
  fromPubkey: agentWallet.publicKey,
  toPubkey: new PublicKey(process.env.BUNKHOUSE_ADDRESS),
  lamports: 0.05 * LAMPORTS_PER_SOL,
});
ix.keys.push({
  pubkey: new PublicKey(process.env.BUNKHOUSE_FUNDING_KEY),
  isSigner: false,
  isWritable: false,
});
await sendAndConfirmTransaction(connection, new Transaction().add(ix), [agentWallet]);

Save the address and your funding key as secrets so the agent can read them. The funding key is not a secret in the cryptographic sense: it can only add money to your balance, never take any.

Move in an agent