PocketContext
Prova in locale

Installazione

Sei tu che accedi. Non installi il database.

Installazione di PocketContext per te

Questa guida è per chi usa un’app. Di solito è qualcun altro a eseguire il server. Tu accedi e, se vuoi, installi uno skill piccolo così un assistente di programmazione può leggere e aggiornare i record insieme a te.

Se sei tu a installare il server, a compilarlo o a creare la macchina cloud, usa prima la guida del server.

Che cosa stai scegliendo

flowchart TB
  you[Tu]
  you --> browser[Usa solo il sito]
  you --> laptop[Installa uno skill su questo computer]
  you --> vps[Installa uno skill su un VPS a cui accedi con SSH]
  you --> localapp[Esegui un’app locale su questo computer]

  browser --> read[Leggi e, in NotifyContext, scrivi anche]
  laptop --> agent[Assistente su questo computer]
  vps --> agentcloud[Assistente sul VPS]
  localapp --> linkedin[LinkContext o NetworkContext]
Modo Che cosa installi Dove sta il database
Browser Niente Sul server che esegue il tuo amministratore
Skill su questo computer Uno skill, uv e un accesso Sempre su quel server
Skill su un VPS Lo stesso skill, sul VPS Sempre su quel server, che può essere una macchina diversa dal VPS
App LinkedIn locali L’app e un server locale Su questo computer

Uno skill è una cartella di istruzioni più un comando, come wikicontext o dealcontext. Il comando parla con il server. Non contiene i dati dell’azienda.

Variabili d’ambiente

Ogni skill ha bisogno di due dati nell’ambiente che avvia l’assistente: dove si trova il server e quale email sei. Una variabile password serve solo per un account che il tuo amministratore ha creato con una password. L’accesso con Google non la usa. Imposta le variabili in quell’ambiente. Non incollarle nel comando e non usare la password dell’operatore. Quell’account è per la schermata di amministrazione.

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

Il nome del comando è il nome dell’applicazione in minuscolo, come wikicontext o dealcontext. Usa https:// a meno che il server non sia su questo computer. Un server locale è http://127.0.0.1: più la porta scelta dal tuo amministratore. Chiedi al tuo amministratore l’origine. Ogni applicazione ha il proprio accesso, quindi una sessione del wiki non apre il CRM.

1. Solo il browser

Apri l’origine che ti ha dato il tuo amministratore e accedi con l’account Google che si aspetta. Quando l’accesso just-in-time è attivo per il tuo dominio Workspace, il primo accesso riuscito può creare il tuo account nell’applicazione. Non ti rende un operatore.

A che cosa serve il browser dipende dall’app:

Che cosa apri Che cosa puoi fare lì
DealContext, TaskContext, RaiseContext, PeopleContext, AccountContext, WikiContext, ChatContext, LinkContext, NetworkContext Leggi. Gli aggiornamenti li fa l’assistente.
NotifyContext Leggi, scrivi una nota e segna di averla vista. Aprire una nota non la segna da sola come letta.
VaultContext Leggi la guida di configurazione. Il sito non sblocca i file.

I visitatori di ChatContext sono diversi dai colleghi. Un visitatore dimostra un’email con un codice monouso e poi vede solo la propria conversazione di assistenza. I colleghi usano Google.

sequenceDiagram
  participant You
  participant Browser
  participant App as Il server dell’app

  You->>Browser: apri l’origine
  Browser->>App: accesso con Google
  App-->>Browser: il tuo lettore

Puoi fermarti qui se volevi solo dare un’occhiata.

2. Uno skill su questo computer

È il modo abituale per lasciare che un assistente di programmazione lavori in un’app. L’assistente e lo skill girano sullo stesso computer tuo. I dati dell’app restano sul server.

Ti servono:

  • uv, che al primo uso scarica il pacchetto Python fissato dello skill.
  • Python 3.11 o più recente, che uv può fornire.
  • Node.js, solo se installi lo skill con npx. Senza Node, copia a mano la cartella dello skill da un clone del repository dell’app nella cartella da cui il tuo assistente legge gli skill.

Anche il comando di VaultContext ha bisogno di Linux o macOS, perché la sessione sbloccata usa un socket Unix. Il binario del server pubblicato non copre i Mac Intel, ma quel limite riguarda l’esecuzione del server. Lo skill in sé è un comando Python.

Installa lo skill

L’esempio di DealContext, per un assistente come Claude Code, dal README dell’app:

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

--list mostra i nomi degli skill in un repository prima dell’installazione. -g mette lo skill nella tua cartella utente. Senza -g, finisce nel progetto corrente. --agent indica l’assistente. Se ometti --agent, l’installer te lo chiede.

La stessa forma vale per le altre app. Sostituisci il repository e il nome dello skill:

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

Usa il nome dell’agente che il tuo installer si aspetta. Codex, Claude Code e gli altri si scelgono con --agent. Una cartella copiata è altrettanto valida. Conta il comando dentro la cartella.

Aggiorna in seguito con npx skills update dealcontext -g, oppure copiando di nuovo la cartella. Il server è l’autorità per i dati. Se check dice che lo schema è diverso, vince il server in esecuzione, e uno skill più recente riallinea le note locali.

Puntarlo al server

Metti le due variabili nell’ambiente che avvia l’assistente. Per il wiki, è così:

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

Usa la tua email e l’origine che ti ha dato il tuo amministratore. Ometti la variabile password se userai Google.

Accedi con Google

Dalla directory dello skill, esegui il comando di accesso. Una sola app alla volta. Aspetta che finisca prima di accedere a una seconda app.

./wikicontext login --google

Il comando stampa un indirizzo. Aprilo nel browser su questo stesso computer. Google rimanda il browser a http://127.0.0.1:8765/callback. Lo skill è in ascolto lì per qualche minuto. Il token che conserva è il token dell’applicazione, non la tua password Google. Sta in una cache privata, di solito sotto ~/.cache/ o $XDG_CACHE_HOME, in una cartella che porta il nome dell’app.

sequenceDiagram
  participant You
  participant Skill as Skill su questo computer
  participant Browser
  participant Google
  participant App as Server dell’app

  You->>Skill: login --google
  Skill-->>You: un URL privato
  You->>Browser: apri quell’URL
  Browser->>Google: accedi
  Google->>Skill: callback sulla porta 8765
  Skill->>App: conserva un token dell’applicazione
  You->>Skill: whoami
  Skill-->>You: il tuo nome, l’email e il server

Poi:

./wikicontext whoami
./wikicontext check

whoami stampa chi il server pensa che tu sia. check confronta le note dello skill con le tabelle in esecuzione. Il codice di uscita 0 significa che coincidono.

logout elimina il token su questo computer. Non elimina il tuo account. Le sessioni durano circa sette giorni e si rinnovano finché continui a usare il comando. Dopo una settimana di silenzio, esegui di nuovo login --google.

Se il tuo amministratore ha disattivato l’account, l’accesso fallisce finché non lo riattiva. Disattivare l’account Google in Workspace non fa scadere, da solo, un token dell’applicazione già emesso. Quella parte è il passaggio con cui l’amministratore chiude l’accesso.

3. Uno skill su un VPS

Usalo quando l’assistente di programmazione gira su un computer cloud e tu raggiungi quel computer con SSH. Lo skill si installa sul VPS, con gli stessi passaggi npx o di copia di un laptop. Il server dell’applicazione può essere una macchina completamente diversa. La variabile URL punta comunque all’app, per esempio https://wiki.pocketcontext.com, non al VPS.

L’accesso con Google è la parte che cambia. Lo skill ascolta sulla porta 8765 sul VPS. Il browser è sul tuo laptop. Un 127.0.0.1:8765 diretto sul laptop è il laptop, non il VPS.

Dal laptop, inoltra quella porta, poi tieni aperta la sessione SSH:

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

Sul VPS, in quella sessione, esegui login --google. Apri l’URL stampato nel browser sul laptop. La porta 8765 del laptop è inoltrata al VPS, quindi il callback raggiunge lo skill.

sequenceDiagram
  participant Laptop as Browser sul tuo laptop
  participant VPS as Skill sul VPS
  participant App as Server dell’app

  Note over Laptop,VPS: ssh -L 8765 invia il callback al VPS
  VPS->>Laptop: URL di accesso stampato
  Laptop->>VPS: Google torna alla porta 8765
  VPS->>App: token dell’applicazione, in cache sul VPS

Il token resta sul VPS. Accedere sul laptop non fa accedere l’assistente sul VPS. Ripeti l’accesso su ogni macchina dove gira uno skill.

Il VPS in questa sezione è la tua postazione di lavoro nel cloud. Non è il server PocketContext, a meno che il tuo amministratore non ci abbia messo anche il server. Installare uno skill non crea mai pb_data.

L’accesso con password salta il browser. Se il tuo amministratore ti ha dato una password, imposta la variabile password di quell’app ed esegui whoami. Preferisci Google quando il server è configurato per quello. Non mettere la password nella riga di comando né in una chat.

4. VaultContext, dopo Google

Google dimostra il tuo nome. Una passphrase sblocca i file. Sono due passaggi.

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

init si esegue una volta, in un terminale davanti al quale sei seduto, e chiede la passphrase. unlock la chiede di nuovo quando vuoi una sessione. La sessione vive su quel computer, per lo stesso utente del sistema operativo, per 15 minuti, a meno che tu non passi un --timeout più lungo, fino a un’ora. lock la termina. Non c’è una chiave di recupero. Perdere la passphrase, senza una sessione sbloccata e senza una voce del Keychain di macOS registrata, lascia i file illeggibili.

Digita tu la passphrase. Non metterla in una variabile d’ambiente, in una chat o in un argomento del comando.

Su un Mac puoi registrare la passphrase nel Keychain dopo init. Quella registrazione è solo per macOS. Un VPS Linux ti chiederà di digitare la passphrase. Se lo skill gira sul VPS, la sessione di sblocco è sul VPS, e il VPS è considerato affidabile per i file sbloccati durante quella sessione.

La pagina pubblica su https://vault.pocketcontext.com è la guida di avvio. Non sblocca nulla.

flowchart LR
  google[Accesso con Google]
  phrase[Passphrase nel tuo terminale]
  session[Sessione sbloccata su questo computer]
  files[File cifrati sul server]
  google --> phrase --> session
  session --> files

5. App locali su questo computer

LinkContext e NetworkContext possono girare interamente sulla tua macchina. Entrambi usano come predefinito http://127.0.0.1:8095. Avviane uno, oppure scegli un’altra porta per il secondo. Non condividono un database.

NetworkContext

È l’archivio di ciò che vede un account LinkedIn. La prima versione non ha accesso con Google né un sito ospitato. Ti servono un checkout di NetworkContext e un binario pocketcontext compilato dal commit nel POCKETCONTEXT_VERSION di quell’app. Compilare quel binario è la guida del server.

Poi, dalle istruzioni dell’app:

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 avvia il server, crea un account e conserva una password casuale in ~/.config/networkcontext/local.json. I comandi successivi trovano quel file. Il database è sotto ~/.local/share/networkcontext/. Il lettore è su http://127.0.0.1:8095/.

Il passaggio di acquisizione è un agente del browser che legge le pagine LinkedIn e scrive un file. networkcontext ingest conserva quel file. L’app non pubblica, non mette mi piace e non invia nulla.

LinkContext

È l’archivio LinkedIn condiviso del team. In locale può avviare un utente da LINKCONTEXT_LOCAL_USER_EMAIL e LINKCONTEXT_LOCAL_USER_PASSWORD, poi servire sulla porta 8095. Ti serve comunque il binario del server fissato, dalla guida del server. L’origine pubblica https://link.pocketcontext.com è quella che il README prevede di usare. Finché non esiste, il server locale è quello che hai.

Su un LinkContext locale, l’accesso con password è il percorso normale. login --google è per un server in cui l’accesso con Google è stato configurato.

Quando qualcosa non accede

Che cosa vedi Che cosa significa di solito
Il comando indica una variabile mancante ed esce Imposta quella variabile nell’ambiente, poi riprova.
Il browser non raggiunge la porta 8765 Su questo computer, nient’altro deve occupare la 8765 durante l’accesso. Su un VPS, l’inoltro SSH deve essere attivo, e apri l’URL sul laptop.
whoami mostra un’email diversa da quella che ti aspettavi Le variabili e il token in cache non coincidono. Esegui logout, correggi l’email e accedi di nuovo.
check segnala una differenza Lo schema del server e le note dello skill sono diversi. Chiedi al tuo amministratore prima di considerare le note dello skill più recenti del server.
L’accesso con Google funziona, ma l’app nega l’accesso Il dominio Workspace potrebbe non coincidere, oppure un amministratore ha disattivato l’account. Un nuovo utente Google non è un operatore.
L’accesso a Vault funziona e i file non si aprono Google ha finito, e unlock non è stato eseguito in un terminale su questo computer. La passphrase è quella che hai scelto con init. La stessa passphrase funziona su un altro computer per lo stesso account. Una passphrase diversa no.

Accedi a un’app, verifica che whoami riesca, poi passa all’app successiva.

Scegli una guidaOspita il server in autonomia