Installing PocketContext for yourself

This guide is for a person who uses an app. Someone else usually runs the server. You sign in, and you optionally install a small skill so a coding assistant can read and update records with you.

If you are the person who installs the server, builds it, or creates the cloud machine, use the server guide first.

What you are choosing

flowchart TB
  you[You]
  you --> browser[Use the website only]
  you --> laptop[Install a skill on this computer]
  you --> vps[Install a skill on a VPS you SSH into]
  you --> localapp[Run a local app on this computer]

  browser --> read[Read, and in NotifyContext also write]
  laptop --> agent[Assistant on this computer]
  vps --> agentcloud[Assistant on the VPS]
  localapp --> linkedin[LinkContext or NetworkContext]

Way	You install	The database lives
Browser	Nothing	On the server your admin runs
Skill on this computer	A skill, uv, and a login	Still on that server
Skill on a VPS	The same skill, on the VPS	Still on that server, which can be a different machine from the VPS
Local LinkedIn apps	The app and a local server	On this computer

A skill is a folder of instructions plus a command, such as wikicontext or dealcontext. The command talks to the server. It does not contain the company's data.

Environment variables

Every skill needs two facts in the environment that starts the assistant: where the server is, and which email you are. A password variable is only for an account your admin created with a password. Google login does not use it. Set the variables in that environment. Do not paste them into the command, and do not use the operator password. That account is for the admin screen.

export <APP>_URL=https://<app>.example.com
export <APP>[email protected]

The command name is the application name in lower case, such as wikicontext or dealcontext. Use https:// unless the server is on this computer. A local server is http://127.0.0.1: plus the port your admin chose. Ask your admin for the origin. Each application has its own login, so a wiki session does not open the CRM.

1. Browser only

Open the origin your admin gave you and sign in with the Google account they expect. When just-in-time sign-in is turned on for your Workspace domain, the first successful sign-in can create your application account. It does not make you an operator.

What the browser is for depends on the app:

You open	What you can do there
DealContext, TaskContext, RaiseContext, PeopleContext, AccountContext, WikiContext, ChatContext, LinkContext, NetworkContext	Read. The assistant does the updates.
NotifyContext	Read, write a note, and mark that you saw one. Opening a note does not by itself mark it read.
VaultContext	Read the setup guide. The site does not unlock files.

ChatContext visitors are different from teammates. A visitor proves an email with a one-time code and then sees only their own support conversation. Teammates use Google.

sequenceDiagram
  participant You
  participant Browser
  participant App as The app server

  You->>Browser: open the origin
  Browser->>App: Google sign-in
  App-->>Browser: your reader

You can stop here if you only wanted to look.

2. A skill on this computer

This is the usual way to let a coding assistant work in an app. The assistant and the skill run on the same computer as you. The app's data stays on the server.

You need:

uv, which downloads the skill's pinned Python package on first use.
Python 3.11 or newer, which uv can provide.
Node.js, only if you install the skill with npx. Without Node, copy the skill folder by hand from a clone of the app repository into the folder your assistant reads skills from.

VaultContext's command also needs Linux or macOS, because the unlocked session uses a Unix socket. The published server binary does not cover Intel Macs, but that limit is about running the server. The skill itself is a Python command.

Install the skill

The DealContext example, for an assistant such as Claude Code, from the app's README:

npx skills add pocketcontext/dealcontext --skill dealcontext --agent claude-code -g -y

--list shows the skill names in a repository before you install. -g puts the skill in your user folder. Without -g, it lands in the current project. --agent names the assistant. If you leave --agent off, the installer asks.

The same shape works for the other apps. Replace the repository and the skill name:

npx skills add pocketcontext/wikicontext --skill wikicontext --agent claude-code -g -y
npx skills add pocketcontext/notifycontext --skill notifycontext --agent claude-code -g -y
npx skills add pocketcontext/taskcontext --skill taskcontext --agent claude-code -g -y
npx skills add pocketcontext/vaultcontext --skill vaultcontext --agent claude-code -g -y

Use the agent name your installer expects. Codex, Claude Code, and others are selected with --agent. A copied folder is just as valid. The command inside the folder is what matters.

Update later with npx skills update dealcontext -g, or by copying the folder again. The server is the authority for the data. If check says the schema differs, the live server wins, and a newer skill brings the local notes back in line.

Point it at the server

Put the two variables in the environment that starts the assistant. For the wiki, that looks like:

export WIKICONTEXT_URL=https://wiki.pocketcontext.com
export [email protected]

Use your own email and the origin your admin gave you. Omit the password variable when you will use Google.

Sign in with Google

From the skill directory, run the login command. Only one app at a time. Wait until it finishes before you log into a second app.

./wikicontext login --google

The command prints an address. Open it in your browser on this same computer. Google sends the browser back to http://127.0.0.1:8765/callback. The skill is listening there for a few minutes. The token it stores is the application token, not your Google password. It sits in a private cache, typically under ~/.cache/ or $XDG_CACHE_HOME, in a folder named for the app.

sequenceDiagram
  participant You
  participant Skill as Skill on this computer
  participant Browser
  participant Google
  participant App as App server

  You->>Skill: login --google
  Skill-->>You: a private URL
  You->>Browser: open that URL
  Browser->>Google: sign in
  Google->>Skill: callback on port 8765
  Skill->>App: store an application token
  You->>Skill: whoami
  Skill-->>You: your name, email, and server

Then:

./wikicontext whoami
./wikicontext check

whoami prints who the server thinks you are. check compares the skill's notes with the live tables. Exit 0 means they match.

logout deletes the token on this computer. It does not delete your account. Sessions last about seven days and renew while you keep using the command. After a quiet week, run login --google again.

If your admin disabled the account, sign-in fails until they enable it. Turning the Google account off in Workspace does not, by itself, expire an application token that was already issued. That part is the admin's offboarding step.

3. A skill on a VPS

Use this when the coding assistant runs on a cloud computer, and you reach that computer with SSH. The skill is installed on the VPS, with the same npx or copy steps as on a laptop. The application server can be a completely different machine. The URL variable still points at the app, for example https://wiki.pocketcontext.com, not at the VPS.

Google login is the part that changes. The skill listens on port 8765 on the VPS. Your browser is on your laptop. A direct 127.0.0.1:8765 on the laptop is the laptop, not the VPS.

From the laptop, forward that port, then keep the SSH session open:

ssh -L 8765:127.0.0.1:8765 user@your-vps

On the VPS, in that session, run login --google. Open the printed URL in the browser on the laptop. The laptop's port 8765 is forwarded to the VPS, so the callback reaches the skill.

sequenceDiagram
  participant Laptop as Browser on your laptop
  participant VPS as Skill on the VPS
  participant App as App server

  Note over Laptop,VPS: ssh -L 8765 sends the callback to the VPS
  VPS->>Laptop: printed login URL
  Laptop->>VPS: Google returns to port 8765
  VPS->>App: application token, cached on the VPS

The token stays on the VPS. Logging in on your laptop does not sign in the assistant on the VPS. Repeat login on each machine where a skill runs.

The VPS in this section is your workstation in the cloud. It is not the PocketContext server unless your admin also put the server there. Installing a skill never creates pb_data.

Password login skips the browser. If your admin gave you a password, set the password variable for that app and run whoami. Prefer Google when the server is set up for it. Do not put the password in the command line or in a chat.

4. VaultContext, after Google

Google proves your name. A passphrase unlocks the files. They are two steps.

export VAULTCONTEXT_URL=https://vault.pocketcontext.com
export [email protected]
vaultcontext login --google
vaultcontext init
vaultcontext unlock

init runs once, in a terminal you are sitting at, and asks for the passphrase. unlock asks again when you want a session. The session lives on that computer, for the same OS user, for 15 minutes unless you pass a longer --timeout up to one hour. lock ends it. There is no recovery key. Losing the passphrase, with no unlocked session and no enrolled macOS Keychain entry, leaves the files unreadable.

Type the passphrase yourself. Do not put it in an environment variable, a chat, or a command argument.

On a Mac, you can enroll the passphrase in Keychain after init. That enrollment is macOS only. A Linux VPS will ask you to type the passphrase. If the skill runs on the VPS, the unlock session is on the VPS, and the VPS is trusted with the unlocked files for that session.

The public page at https://vault.pocketcontext.com is the onboarding guide. It does not unlock anything.

flowchart LR
  google[Google login]
  phrase[Passphrase in your terminal]
  session[Unlocked session on this computer]
  files[Encrypted files on the server]
  google --> phrase --> session
  session --> files

5. Local apps on this computer

LinkContext and NetworkContext can run entirely on your machine. They both default to http://127.0.0.1:8095. Start one, or pick another port for the second. They do not share a database.

NetworkContext

This is the archive of what one LinkedIn account sees. The first version has no Google login and no hosted site. You need a checkout of NetworkContext and a pocketcontext binary built from the commit in that app's POCKETCONTEXT_VERSION. Building that binary is the server guide.

Then, from the app's own instructions:

networkcontext local init --app-dir /path/to/networkcontext --binary /path/to/pocketcontext
networkcontext account add --url https://www.linkedin.com/in/you/ --name "Your Name"
networkcontext whoami
networkcontext check

local init starts the server, creates one account, and stores a random password in ~/.config/networkcontext/local.json. Later commands find that file. The database is under ~/.local/share/networkcontext/. The reader is at http://127.0.0.1:8095/.

The capture step is a browser agent reading LinkedIn pages and writing a file. networkcontext ingest stores that file. The app does not post, like, or send anything.

LinkContext

This is the team's shared LinkedIn store. Locally it can bootstrap one user from LINKCONTEXT_LOCAL_USER_EMAIL and LINKCONTEXT_LOCAL_USER_PASSWORD, then serve on port 8095. You still need the pinned server binary from the server guide. The public origin https://link.pocketcontext.com is the one the README plans to use. Until that exists, the local server is the one you have.

On a local LinkContext, password login is the normal path. login --google is for a server where Google sign-in has been configured.

When something does not sign in

What you see	What it usually means
The command names a missing variable and exits	Set that variable in the environment, then try again.
The browser cannot reach port 8765	On this computer, nothing else should own 8765 during login. On a VPS, the SSH forward has to be up, and you open the URL on the laptop.
`whoami` shows a different email than you expected	The variables and the cached token disagree. `logout`, fix the email, and log in again.
`check` reports a difference	The server schema and the skill notes differ. Ask your admin before you treat the skill's notes as newer than the server.
Google sign-in works, but the app denies access	The Workspace domain may not match, or an admin disabled the account. A new Google user is not an operator.
Vault login works and files do not open	Google finished, and `unlock` has not been run in a terminal on this computer. The passphrase is the one you chose at `init`. The same passphrase works on another computer for the same account. A different passphrase will not.