Atlas setup guide / Version 0.25.0

A little setup.
A lot more context.

Start with a few notes. Let your agent connect them. Keep the knowledge for whatever comes next.

Atlas is the new name of the Atlas knowledge base. Atlas 0.25.0 and its commands still use the original name, so this guide does too.

01 / Get ready

Choose where your knowledge lives.

Atlas is one program containing a local server, a browser reader and a command-line client. Coding agents operate it using an installed skill; compatible chat apps connect through its optional MCP endpoint. You use your own agent and any model or tool subscriptions it requires.

On your computer

A good starting point when your notes and your agent are on the same machine. Confirm a folder and a name; your agent handles installation and checks. Your computer needs to be awake for work to run.

On an always-on computer

Keep the knowledge base on a computer that stays on, then connect your other computers as clients. Each can have its own agent. One generated client prompt connects them to the same knowledge.

The 0.25.0 release supports Linux amd64 and arm64, Apple Silicon Macs on macOS 15 or later, and Windows amd64. Start with the website setup prompt; your server’s agent generates a complete client prompt when you want to connect another computer. It checks the platform and asks only the questions needed for your choice.

Get the setup prompt

Your knowledge, on your phone

One link. Your own reader.

Ask your setup agent to make Atlas available on a domain you control. It configures the same binary on an always-on host, checks the connection and gives you a secure sign-in link to open on your phone. Atlas manages the HTTPS certificate and its renewal. No app, tunnel client or separate web server is needed on your phone.

You need a domain and a host reachable from the internet. Your agent checks these first and explains any missing DNS, router or hosting step. Local-only use remains the default. Keep the host running to read away from home.

Browse published pages, search your knowledge and inspect the sources behind a citation. Your external agent performs ingestion and synthesis through the CLI and installed skill. HTTPS hosting guide

Your knowledge, your agent

One MCP connection.
Your choice of agent.

MCP is an open protocol for connecting agents to tools and knowledge. Atlas’s endpoint works with compatible MCP clients; it is not tied to one model or vendor. Choose a chat app, coding agent or always-on agent below.

  1. Enable MCP on your domain.

    Ask your setup agent for MCP access. It enables --mcp on your existing HTTPS service and checks https://your-domain/mcp. Your host must stay awake and reachable. No separate identity provider, agent runtime or private tunnel is needed.

  2. Sign in to your Atlas reader.

    Open the short-lived reader link from your setup agent in the browser profile you will use to approve the connection. You do not need the password generated during setup.

  3. Add the URL and approve access.

    Follow your client’s instructions below. Use Streamable HTTP and OAuth when asked. Atlas supports automatic client registration, so leave optional client IDs and secrets empty. If consent asks you to sign in, open a fresh reader link in another tab of that browser profile, then return.

  4. Verify one useful read.

    Ask your agent to list your spaces or find a published page. Check the result against your reader. Test the same read on your phone if you plan to use it there; attachment, voice and background access depend on the client.

Your server URLhttps://your-domain/mcp

Replace your-domain with your Atlas HTTPS domain.

Instructions follow vendor documentation reviewed November 5, 2026. These are setup routes, not claims of completed Atlas account or mobile tests. Features and permissions depend on your client, plan and workspace.

Chat apps

Bring your knowledge into the conversations you already use.

Claude

Open Customize, then Connectors. Choose Add custom connector, name it Atlas and enter your MCP URL. Leave advanced OAuth credentials empty, add the connector and complete browser consent. In managed workspaces, an owner may need to add it first.

Claude custom connectors

ChatGPT

On desktop: open Settings, then MCP servers. Add a server named Atlas, select Streamable HTTP and enter your URL. Save, restart when prompted and select Authenticate.

On the web: use the custom MCP connection or plugin creation flow available in your workspace. Ask Plugin Creator to connect your Atlas MCP URL, install the resulting plugin and complete its sign-in prompts. Desktop MCP settings do not automatically install a hosted plugin. Confirm the tools appear in the chat where you will use them.

ChatGPT MCP setup · Custom MCP plugins

Gemini

On Gemini web, open Settings, Connected Apps, then Custom apps. Some accounts show Connected Apps under Personal Intelligence. Add your MCP URL, select Next and approve access. Leave advanced credentials empty. Use an @ mention to select your custom app in a chat or task.

Google currently lists English, US, adult personal accounts with Keep Activity enabled as requirements. Connect on the web first, then verify a read in the mobile app.

Gemini custom apps

Grok

Open grok.com/connectors, choose New Connector, then Custom, and enter your MCP URL. Complete the authentication flow and ask Grok for a read. A Business or Enterprise administrator may need to provision the connector before you can connect it.

Grok connectors

Coding agents

Connect over MCP, or keep using Atlas’s CLI and installed skill for local work. Replace the example domain before running a command.

Claude Code
claude mcp add --transport http pocketcontext https://your-domain/mcp

Start Claude Code, open /mcp and authenticate Atlas in your browser. Then ask for your spaces.

Claude Code MCP guide

Codex
codex mcp add pocketcontext --url https://your-domain/mcp
codex mcp login pocketcontext

Complete browser consent, then check /mcp in Codex. The CLI and IDE extension share their MCP configuration.

Codex MCP guide

Google Antigravity

Open the MCP manager for your surface: Customizations in the app, /mcp in the CLI, or Manage MCP Servers in the IDE. Add this entry to the existing mcpServers map in its configuration; keep any other servers.

"pocketcontext": {
  "serverUrl": "https://your-domain/mcp"
}

Refresh the server list and choose Authenticate. Follow Antigravity’s browser handoff and return to the app when prompted. Automatic OAuth registration needs no manually supplied credentials.

Antigravity MCP guide

Grok Build
grok mcp add --transport http pocketcontext https://your-domain/mcp

Complete OAuth when prompted on first use. Open /mcps to inspect the server or authenticate it. Use grok mcp doctor pocketcontext if the connection fails.

Grok Build MCP guide

Pi
pi mcp add pocketcontext --url https://your-domain/mcp
pi mcp login pocketcontext

Approve access in the browser. Use /reload if Pi is already running, then /mcp to check the connection. These steps use Pi’s current built-in MCP support; an installed MCP extension can replace that interface.

Pi MCP guide

Always-on agents

Give an agent ongoing work with your knowledge. Verify a one-time read before asking it to monitor or update anything on a schedule.

Grok Bot

Tell your Bot: “Add this MCP server: https://your-domain/mcp.” Confirm the connection details and follow its authentication handoff. Ask for a read in your next message. Your organization’s connector and network policies may restrict which servers it can reach.

Grok Bot custom connector instructions

Claude Duet

Add and authorize Atlas through Claude’s custom connector flow above. Duet can use connected Claude apps, but some connectors have additional limits. Ask Duet to find a known page and confirm that your custom connector is available before assigning ongoing work.

The shared connector route is documented; Atlas access in the Duet research preview has not been verified.

Claude Duet connected apps

dots in ChatGPT

Set up Atlas through the ChatGPT hosted plugin route above, then install, enable and connect that plugin for your account. Ask your dot to read a known page. Dots use supported account plugins; a local Codex MCP entry alone does not make the connection available to your dot in the cloud.

Plugin access depends on the dot’s environment and permissions. Atlas access through a dot has not been verified.

Connect apps to your dot

Gemini Tasks formerly Gemini Spark

Connect Atlas in Gemini web using the Gemini instructions above. Choose Task beside the prompt box and select your custom app for the task. Confirm one read before adding a schedule. Google renamed Spark to Task; access to task features depends on your subscription.

Gemini tasks and workflows

Muse by Meta

Muse supports connected apps and ongoing work, but we have not confirmed an official setup route for an arbitrary remote MCP URL with Atlas’s OAuth. A connector catalog alone does not establish custom MCP support.

Check the connection options available in your Muse account. If it offers a custom MCP server with Streamable HTTP and OAuth, use the generic instructions below and verify a read. Otherwise, use one of the documented clients above.

Muse product information

Other MCP clients

Generic MCP instructions

Choose a client that supports remote Streamable HTTP, OAuth discovery and dynamic client registration. Add https://your-domain/mcp as a remote server, complete the browser consent flow and check that its knowledge tools appear.

Desktop apps may receive the authorization on their own callback at http://127.0.0.1 or http://[::1], which Atlas accepts since 0.25.0. Callbacks on localhost, LAN addresses or custom URI schemes are refused.

Ask it to list spaces, then retrieve a page you can check in the reader. A client that only supports local stdio, requires a fixed API key, or cannot complete OAuth needs a different integration route. Your setup agent can also use Atlas’s CLI and skill where command execution is available.

Atlas MCP reference

MCP tools cover knowledge and space operations, including ingestion, extraction submission, staging and publication. They preserve citation and conflict checks. Server administration stays local. Review or revoke access at https://your-domain/oauth/connections.

Your knowledge, another computer

Read on your own computer.

Ask your knowledge base’s agent to connect another computer. It generates one client setup prompt containing an invitation. Copy that entire prompt from the server’s chat and paste it into the other computer’s agent. The agent installs the client if needed, checks the server’s identity, connects the tunnel and requests the signed-in reader on your desktop. If setup runs through SSH or on a machine without a usable desktop, it skips browser sign-in there and guides you to your own computer.

No separate invitation file or login code to copy. Sharing the invitation in your setup chats is part of this flow. If its one-time code expires during installation, keep the installed client and request a fresh invitation. The server and its tunnel must remain running; the client saves its connection and can restart its managed forward later.

A clear home for each project

Several knowledge bases. Choose by name.

Give each knowledge base a name such as “alpha” or “research.” Your agent’s router finds its matching skill and verifies the project before using it. Ask “ingest these notes in pocketcontext alpha” or “search alpha and research.” Results stay labelled, and evidence citations remain inside their knowledge base and space.

A knowledge base is a separate database; a space is a partition inside it. If a write does not name a knowledge base and you have not chosen a default, your agent asks before writing.

02 / The first useful thing

Turn two notes into one answer.

  1. Set up with your agent.

    Copy a setup prompt, review it and paste it into an agent that can run commands on the intended computer. It will check the environment and report what it installed.

  2. Choose a small set of notes.

    Try a project brief and meeting notes. Version 0.25.0 reads UTF-8 text itself: Markdown, TXT, CSV, JSON, RST, LOG, SRT and Org. It also keeps PDFs, images, audio and other files up to 50 MiB, which your agent converts to text.

  3. Ask for connected knowledge.

    Have the agent read the imported sources, synthesize a page, attach citations and publish it. Importing a file alone does not create a published knowledge page.

  4. Ask a question and follow the evidence.

    Open the reader to explore the page, its properties, revisions and cited passages. Tell the agent to flag conflicting or missing evidence instead of filling in the gaps.

Try asking

“Read these two project notes. Create a short project overview with citations, highlight any conflicting dates, and publish it in Atlas.”

The website examples are fictional. After setup, you can choose to import the Atlas manual into its own space and try a cited backup guide, or use a clearly labelled synthetic example. Imported sources remain in the project’s history.

03 / Bring context together

Your tools provide the information.
Your agent makes the connection.

Your agent can collect accessible text from tools such as Notion, Evernote, Obsidian, Jira, ClickUp, HubSpot, Pipedrive, Gmail and Google Docs, using the connectors, exports or browser access available to it. Atlas stores the resulting evidence and knowledge.

These are agent workflows, not bundled Atlas integrations. Access depends on the source service, the agent’s tools and your permissions. Start with one source you already use and verify its workflow before adding others. For an existing Obsidian vault, an optional import script from the Atlas source repository can bring a one-time copy; see Good to know.

Keep a useful trail.

Ask your agent to retain the source system, original record ID or link, and the time it read the information. A local copy answers questions about what was captured; a fresh sync is needed to know what changed later.

To use another interface, your agent can prepare Markdown or write selected content back through an authorized tool. Version 0.25.0 has no built-in exporter or automatic two-way sync. Define which system owns each field before reconciling changes.

04 / Make it a habit

Build on what you already know.

Once your sources are in one place, ask your agent to join information across them, check your own rules and propose updates. Atlas’s authenticated, read-only SQL interface lets the agent query captured records together; changes go through the application API.

A weekly review

“Review my project pages. Find decisions without supporting evidence, dates that conflict across sources, and information that hasn’t been checked in a month. Give me a short list of proposed corrections.”

Use your agent’s scheduling feature for recurring work. Atlas does not include a scheduler, model or built-in chat. Local queries avoid fetching the same remote records for every question; external syncs and model calls still follow their providers’ limits.

05 / Keep control

A small project folder.
A complete knowledge history.

Atlas/
  pocketcontext        # The program (pocketcontext.exe on Windows)
  pocketcontext.db     # Knowledge and history
  pocketcontext.json   # Project configuration
  storage/             # Original source files

The setup prompts install the program into the project folder, beside the database, so the project keeps the release that can open it. The installers have no default location: you name the folder. For a project synced across operating systems, keep a versioned program on each computer outside the synced folder and let its profile select the database explicitly. Mac and Linux programs share a name. Keep a synced project folder downloaded on the computer that runs it, and if others can write to the folder, check the program’s version before using it. Machine-specific tokens and runtime files stay in a private cache. Back up the database, configuration, originals and matching program together, using a consistent snapshot after a clean pocketcontext stop. Keep the backup on a separate destination and verify that you can restore it.

The setup prompts do not automatically configure backups. On an always-on host, the database lives there; the connected client does not keep a second database. You can sign in to the same server from your other computers as clients, but only one computer should run a given project’s server at a time.

If your agent uses a cloud model, the content it reads may be sent to that provider. Local storage gives you control over the knowledge base; your agent’s data policies still apply.

A few practical questions

Good to know.

Do I need to move all my notes?

No. Begin with a few useful notes and keep your existing tools. Build a repeatable import workflow once you see value. Sources are preserved as evidence, and your agent can synthesize connected pages from them.

Can I bring over an existing Obsidian vault?

Yes, as a one-time copy, with some setup. Version 0.12.0 added an optional import script to the Atlas source repository; it is not part of the program. It needs Python 3.10 or later and a copy of the source code matching your release, and works with a project on the same computer, for vaults whose collections keep original files in a raw/ folder beside their pages. It audits the vault before writing anything, then makes each collection a space: originals become sources, and notes become pages that keep their wording, links, images and footnotes. Imported pages are marked as needing verification, and their footnotes stay attribution rather than checked citations. Missing files and unresolved links are reported, not guessed, and an interrupted import can resume. It does not keep the vault in sync. Your agent’s Atlas skill describes the workflow.

Can I read my knowledge from my phone?

Yes. Ask your agent for HTTPS hosting on a domain you control. Atlas serves the reader and automatically manages its certificate in the same binary. Open the verified sign-in link in your phone browser; no Atlas client or tunnel is needed. A domain and an internet-reachable, always-on host are required. Set up phone access.

Can I chat with my knowledge from my phone?

Atlas has no built-in chat. With MCP enabled on your HTTPS domain, connect a compatible chat app or always-on agent, approve access and test a read on your phone. The phone reader still provides browsing, search and citations. Client availability and supported tools vary; follow the MCP setup.

Does it work with my agent?

Compatible agents can connect through the optional MCP endpoint; see the client instructions above. For command-line access, the binary can install skills for Claude Code, Codex and Antigravity, or write a skill to a custom directory for another capable agent. An earlier Grok Bot two-computer workflow, using a separately installed Tailcat, has a recorded setup verification. Compatibility depends on command execution, file access and the ability to read and follow the skill; other agents need verification.

How do spaces and navigation work?

A project belongs to one person, and spaces simply partition your knowledge, for example by subject. There are no Personal or Company spaces, members or roles. A new project starts with one space, Default. Manage spaces in the reader, or your agent, can create, rename, archive and restore spaces and choose which one is the default. Archived spaces stay readable but accept no changes, and the default space cannot be archived. Your agent can organize published pages into topics and catalogs using page properties. A page can link to a page in another space; evidence and citations stay within each space.

Can I run the server and tunnel as one service?

Yes. For an initialized project, pocketcontext serve --headless --tunnel runs both in one foreground process. Your agent can configure one operating-system service to restart it after a failure and start it at boot. Stop an existing server before switching: this mode owns both components and refuses to attach to another server. Stopping the combined service stops the tunnel and cleanly writes the database back.

For independent lifetimes, pocketcontext tunnel serve remains available. It starts or reuses a compatible background server and leaves it running when the tunnel stops. Each component needs supervision for crash recovery. Neither tunnel mode creates a missing database. See the permanent-service guide for setup and migration.

What happens when setup runs through SSH?

Your agent finishes the command-line setup and skips launching a browser on the remote host. If you requested public HTTPS hosting, it verifies the domain and gives you a domain sign-in link for your phone. For a private desktop connection, it follows the client handoff below. A localhost link from that host does not automatically reach it from your laptop. If you already asked to connect your computer, setup continues to the client handoff; otherwise your agent offers that once. Paste the generated client prompt into an agent running on the computer where you want to browse. The desktop agent connects first, then generates a fresh reader sign-in link and opens it or shows it for you to click. Return to the server agent afterward and confirm that you could access the knowledge base, or share the desktop agent’s error report. A working tunnel alone does not confirm reader sign-in. Terminal-only clients can stay connected without opening a reader.

Can I keep using a project from an earlier version?

Yes for 0.11.x–0.23.1: their databases need no data migration to 0.25.0. A program update does not always change the database format. Have your agent stage and verify the new release, cleanly stop the project and its affected tunnels, and back up the database, configuration, original files and old program before explicitly replacing it. Then restart, check the running version and project identity, refresh the profile and skill, and check connected clients. The installer refuses an existing program unless the caller names its observed old version; it does not make backups or perform this workflow automatically.

For rollback, restore the complete backup with its matching program; do not assume replacing only the program is safe. Projects from 0.10.0 or earlier remain unsupported and are left unchanged. Keep their own release to read them and transfer needed content into a new project. See the upgrade and rollback guide.

Can different versions run on the same computer?

Yes. Keep one selected release for each project, with its own database folder and registered skill. The router chooses that project’s program; upgrading one project does not upgrade the others. Only one server may run a given project. Readers and remote forwards need available ports, and two remote servers using the same port cannot both be forwarded on one client without explicitly changing a server’s configuration. Use matching server and client releases and restart affected background processes after an upgrade.

How do I find the original evidence?

Use All pages for published knowledge and Sources for original files and their text, including uncited notes. Sources supports search, sorting and pagination. Markdown originals render in the reader; a citation can open and highlight its supporting passage. Pages can also link to an original file and show source images, which the reader displays only after checking their hash, with enlargement and download. Sidebar search follows the section you select.

Can I import PDFs, images or audio?

Yes. Version 0.25.0 stores them unchanged as originals, up to 50 MiB each, without reading them. Your agent converts each one to text with its own abilities, for example by reading the PDF or transcribing the audio, and records that text in Atlas. The reader labels those passages as agent-derived text, not an exact copy, and its Needs extraction filter lists files still waiting for conversion. Atlas never parses these formats or calls an external tool for them.

Is Atlas an AI model?

No. It stores sources and structured knowledge, validates publications, and exposes authenticated search and SQL. Your agent supplies the reasoning and operates it through MCP or the CLI and skill.

Are the pages just Markdown files?

Page revisions contain Markdown bodies and structured JSON properties, linked citations and relationships. They live in the database with their history. An agent can render them as files, including front matter, using a separate export workflow.

Will every answer be correct?

Citations and revision history make answers easier to check. They do not guarantee that an agent interpreted a source correctly. Ask for the supporting passage and review uncertain conclusions before acting.

Where can I check the technical details?

Read the 0.25.0 README, data model, spaces, Obsidian import guide and release notes and downloads. The site’s setup prompts target this specific release.

Start with one useful connection.

Get the setup prompt