Connections

What are connections?

Connections let your agent interact with external services on your behalf. Connect Gmail and your agent can read and send email. Connect GitHub and it can create PRs. Connect Notion and it can update your docs.

The important thing: your agent never sees your actual credentials. A proxy layer swaps in real credentials at request time — the agent only ever works with placeholders. Your real keys and tokens never enter the agent’s environment.

Connecting a service

The easiest way is to just ask your agent. Tell it “connect my GitHub” or “I want you to be able to read my Google Calendar” and it handles the rest.

If it’s an OAuth integration (most common)

Your agent opens a connection screen, you click through the standard authorization flow (Google, GitHub, etc. will ask you to grant access), and you’re done. The token is encrypted and stored. Takes about 10 seconds.

Gmail, GitHub, Notion, Slack, Google Calendar, Google Drive, Linear, Jira, Figma, Discord, Todoist, and dozens more support OAuth.

If it requires an API key

Some services need an API key instead of OAuth. Your agent will tell you exactly where to go — which settings page, what to click, what permissions to select. When you’re ready, it opens a secure input screen where you paste the key.

Never paste credentials directly in chat. Chat messages are stored in conversation history. Always use the secure input popup that your agent opens for you — it keeps the key out of the conversation entirely.

Manual setup

You can also set up connections yourself through the settings panel. Scroll through the list of OAuth providers and click to connect, or add an API key manually. But honestly, just asking the agent is easier — it knows the setup steps for each service and walks you through it.

How OAuth connections work under the hood

OAuth connections are managed through Composio, an OAuth broker. When you authorize a service (Gmail, GitHub, Notion, etc.), Composio handles the token exchange and stores the OAuth token on its infrastructure. Printhouse never sees or stores the raw access token.

When your agent makes a request to an OAuth-connected service, the request passes through two layers:

1. The sandbox credential proxy intercepts the request and identifies the connection by its dummy key
2. The gateway forwards the request to Composio’s proxy, which injects the real OAuth token and makes the upstream call

This means OAuth tokens don’t exist anywhere in Printhouse’s infrastructure — not in the agent’s environment, not in the database, not in the gateway’s memory. They live exclusively in Composio’s managed auth layer.

For API-key-based connections, the architecture is simpler: real keys are encrypted in our database and injected by the sandbox credential proxy directly — they never enter the agent’s environment but they do live in our infrastructure.

Network access

You control what your agent can reach on the internet. Three modes, configurable in settings:

Open access (default) — Your agent can reach any domain. Connected services get automatic credential injection; everything else passes through without credentials. This is the right default for most people — the agent can browse the web, read docs, hit public APIs.

Connections only — Requests must go through a connection, limited to the permissions you granted. It’s not just a domain allowlist — every request must match a specific credential you’ve configured. Even if GitHub is connected, the agent can only use your token with the scopes you authorized. If you didn’t connect it, the request doesn’t leave the sandbox. Use this when you want tight control over what data leaves your workspace.

No external access — Standard outbound web access is blocked except for model-provider calls and internal Printhouse platform services required to operate the agent. Connections are inactive. Use this if you’re working on something sensitive and want the agent to keep working locally without reaching arbitrary external web services.