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
- It keeps running. The process should not exit when its work is done; loop, schedule or wait instead. When it does exit, it is started again and the restart is logged.
- It prints what it does. Write to stdout and stderr. Those lines are your logs.
- It reads settings from environment variables. Every secret you save becomes one, under the name you give it.
- It only calls out. Agents can reach the internet; they do not get a public address or open port.
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.