Skip to content
Pilotoo
v0.1

0.1.0 Latest

ChangelogHow versions work

Remote sources

Introduction

Section titled “Introduction”

A server does not need its own vault to give agents connection tools. Point it at a service that exposes the Tools API, such as Pilotoo Connect. The tools keep their names, connections_search and connections_execute, but call the service. Accounts, credentials and refresh live there.

One service

Section titled “One service”

Create an access token in the service, then set two variables in the server’s environment:

.env
CONNECTIONS_REMOTE_URL=https://connect.example.com
CONNECTIONS_REMOTE_TOKEN=<access token>
apps/api/src/app.module.ts
PilotooModule.forRoot({
  connections: { providers: [], tools: true },
});

Both variables are required; with only one set, the tools come from local storage as before. List the tools in an agent to use them:

tools: [connections_search, connections_execute]

A refusal from the service passes through unchanged. An unreachable service, a timeout (30 seconds) or any other non-success answer is unavailable, and a refused token is forbidden.

Several services

Section titled “Several services”

Set CONNECTIONS_REMOTE_SOURCES to a JSON array instead. It wins over the two variables above.

.env
CONNECTIONS_REMOTE_SOURCES=[{"name":"business","url":"https://connect.example.com","token":"<token>"},{"name":"personal","url":"https://connect.me.example.com","token":"<token>"}]
  • With more than one source, tool names and account ids are prefixed <source>:, such as business:github__list_issues. The same provider in two sources is two distinct tools. With exactly one source nothing is prefixed.
  • When this server also keeps connections of its own, they join as a source named local.
  • Search runs on every source in parallel and interleaves their rankings up to limit. Execute goes to the source in the prefix; an unknown prefix is not_found.
  • A source that is down, times out or answers unavailable to a search is skipped and listed in the answer’s unavailable array. Executing on it answers unavailable.
  • A malformed value stops the boot with a message that does not quote it.

In code, createRemoteToolSource({ baseUrl, token }) and createCompositeToolSource([{ name, source, tools? }]) from @pilotoo/connections-core build the same sources. tools is an allow-list: it can hide a source’s tools, never admit one the source refused.

The desktop app

Section titled “The desktop app”

The local backend turns this on by itself when the environment names a remote service, so the desktop needs only the variables. Add them to ~/.pilotoo/.env and restart the app:

~/.pilotoo/.env
CONNECTIONS_REMOTE_URL=https://connect.example.com
CONNECTIONS_REMOTE_TOKEN=pc_...

Without them there are no connection tools, and the app has no connections screens of its own: connect accounts in the service’s web app. See Local backend.

The desktop reaches Brain the same way, with BRAIN_REMOTE_URL and BRAIN_REMOTE_TOKEN. Its tools are brain_-prefixed MCP tools (brain_memory_search, brain_memory_add_source, brain_workflow_save) and opt-in per agent like these.

Next steps

Section titled “Next steps”