Managed Sync and self-hosting

EtherPK gives you two ways to sync encrypted knowledge graphs between devices.

EtherPK Managed Sync

If you are already signed in on the EtherPK Account site, open the hosted Client and it quietly checks that session through OAuth. The Client then creates its own host-only session, selects the managed Sync Server and shows the confirmed account on its home page and in the top navigation.

If there is no EtherPK Account session to reuse, open Sync settings, choose Managed Sync, then select Continue to secure sign in. You sign in with your EtherPK Account and the Client connects to the managed service automatically. You do not need to copy an access token or enter a server address.

sequenceDiagram
    actor You
    box rgb(239, 246, 255) EtherPK Client app - app.etherpk.com
        participant Client as Browser UI and Client session
    end
    box rgb(245, 243, 255) EtherPK account app - www.etherpk.com
        participant Account as Account sign-in and OAuth
    end
    box rgb(240, 253, 244) Managed Sync Server app - server.etherpk.com
        participant Sync as Sync API
    end

    You->>Client: Open hosted Client or choose Managed Sync
    Client->>Account: Check or open secure sign-in
    alt EtherPK Account session already exists
        Account-->>Client: Confirm without another prompt
    else Sign-in is required
        Account->>You: Show secure sign-in
        You->>Account: Complete sign-in
    end
    Account-->>Client: Return to EtherPK Client
    Client->>Sync: Prove the signed-in account
    Sync-->>Client: Account, plan, limits and owned usage
    Client-->>You: Show the account in navigation and its synced graphs

The EtherPK Account session, Client session and Sync access token remain separate throughout this journey. The diagram shows the visible hand-offs rather than implying that any application shares another application's cookie.

The Client participates in managed authentication because every managed Sync request must prove which account owns or can access a graph, and which plan limits apply. The Client is therefore a public OAuth client with its own host-only session. It requests a short-lived access token only when Sync needs one; the managed Server validates that token before returning the account's graphs or accepting changes.

This is authentication for the Client's Sync connection, not a second account system. After the managed Server confirms the Principal, Client shows the account email in its top navigation. Open that menu for Graphs, Account, Sign out of EtherPK and Disconnect this device. The full name, email, plan and usage remain on Graphs. A Custom server connection uses a Personal Access Token instead of OAuth, but the same top-navigation status and Graphs panel report the identity which that Server has actually confirmed. Client explains the scope immediately above Disconnect this device, using wording appropriate to the managed OAuth or Custom server connection.

Encryption, plans and limits

Your graph content, name, documents, presence and assets are encrypted on your device before they reach the Sync Server. The service can enforce storage and collaboration limits from encrypted byte counts and membership records, but it cannot read your knowledge.

Sync+ pays for operating the managed service. Local graphs, the Client and self-hosting remain free, and a Free account can still join a Sync+ subscriber's graph as a Player. A payment problem does not delete your data straight away: if Sync+ ends, the graphs you own become read-only and you can still read, export and delete them. They are deleted from the managed service after a retention period, so export anything you want to keep. Graphs shared with you belong to their Owner and are unaffected.

The Billing page shows the plan, renewal or paid-through date, exact limits and current aggregate owned usage. A warning appears before owned graphs or encrypted storage reach their hard limit. An offline edit which reaches the allowance stays safely in the encrypted outbox. Upgrade or delete unused owned data, then reconnect to let it retry.

The Client separates Owned by you from Shared with you. Your plan's graph and storage totals count only graphs you own. Joining somebody else's graph does not use one of your owned graph slots. Writes and invited Players on a shared graph use that graph Owner's allowance.

Sign out of EtherPK signs this browser out of the EtherPK Account site, Client and managed Server. It also forgets the Client's in-memory access token and locks locally held vault keys. It does not delete local or synced graphs. Disconnect this device is the narrower Client action: it removes this Client session, locks its locally held vault keys and attempts to revoke its OAuth refresh grant while leaving the Account site and any Server portal session alone. Client then shows Sign in. It reserves Sync unavailable for a Server which cannot be reached or another failure where the current authentication state cannot be confirmed.

The Client never stores the managed access token in browser storage. It keeps only an encrypted, HTTP-only session cookie and requests short-lived access when Sync needs it. If that session is revoked or expires, EtherPK asks you to sign in again and keeps local edits waiting safely for the connection to return.

Changing and verifying your EtherPK Account email does not create a new Sync identity or detach your graphs. EtherPK identifies the account using an immutable provider identity; email and name are profile details which can change independently.

When a managed Sync Server page asks you to sign in, it opens the EtherPK Account sign-in page directly. After successful sign-in, the Account app returns you to the exact Server page which initiated the request. The Server then shows the authenticated account, plan, status and owned usage. It does not gain access to your password or Account session cookie.

sequenceDiagram
    actor You
    box rgb(240, 253, 244) Managed Sync Server app - server.etherpk.com
        participant Portal as Browser-facing Server portal
        participant Server as Portal session and OAuth callback
    end
    box rgb(245, 243, 255) EtherPK account app - www.etherpk.com
        participant Account as Account sign-in and OAuth
    end

    You->>Portal: Open a protected Server page
    Portal->>Server: Request the protected page
    Server->>Server: Remember the requested page
    Server-->>Account: Redirect to secure sign-in
    Account->>You: Sign in or reuse your account session
    You->>Account: Complete sign-in
    Account-->>Server: Return to the fixed Server callback
    Server->>Server: Create its own portal session
    Server-->>Portal: Set the Server session and return the page
    Portal-->>You: Show the requested Server page

The requested page is kept by the Server. It is not sent to the Account app as an unrestricted callback address, so sign-in can return you to the right place without opening an external redirect.

Signing in directly on the Account site initially creates only the EtherPK Account session. On the next managed Server or hosted Client visit, that app checks the Account session through OAuth and can establish its own host-only session without another password prompt. In Client, this automatic check only selects Managed Sync when there is no existing connection, so it does not replace a Custom server chosen on that device.

Disconnect this device suppresses the Client's automatic check for the rest of that browser session. This keeps the Client disconnected while leaving the Account site and Server signed in. Choosing Managed Sync explicitly starts the connection again.

Signing out from any managed app

The Client, EtherPK Account app and Server use three separate host-only sessions:

The Account app remembers the EtherPK Account and handles account security and billing.
Client keeps its own encrypted refresh-session cookie and holds short-lived Sync access tokens in memory.
Server keeps an opaque portal cookie for its own pages and stores the corresponding OAuth tokens encrypted in the Server database.

EtherPK single sign-on usually means moving between them does not require another password prompt, but the sessions are still independent. Sign out of EtherPK coordinates all three origins without sharing those cookies. You can start it from the Account app, Client or Server.

sequenceDiagram
    actor You
    box rgb(239, 246, 255) EtherPK Client app - app.etherpk.com
        participant Client as Client session
    end
    box rgb(245, 243, 255) EtherPK account app - www.etherpk.com
        participant Account as EtherPK Account session
    end
    box rgb(240, 253, 244) Managed Sync Server app - server.etherpk.com
        participant Server as Server portal session
    end

    alt Start in Client
        You->>Client: Sign out of EtherPK
        Client->>Client: Clear Client session and lock vault
        Client->>Account: End EtherPK Account session
        Account->>Server: Continue sign-out
        Server->>Server: Clear Server portal session
        Server-->>Client: Return signed out
    else Start in Server
        You->>Server: Sign out of EtherPK
        Server->>Server: Clear Server portal session
        Server->>Account: End EtherPK Account session
        Account->>Client: Continue sign-out
        Client->>Client: Clear Client session and lock vault
        Client-->>Server: Return signed out
    else Start in Account app
        You->>Account: Sign out of EtherPK
        Account->>Account: End EtherPK Account session
        Account->>Client: Continue sign-out
        Client->>Client: Clear Client session and lock vault
        Client->>Server: Continue sign-out
        Server->>Server: Clear Server portal session
        Server-->>Account: Return signed out
    end

The managed Account and Server menus deliberately provide one sign-out action. Pressing Sign out of EtherPK in either app always starts the complete three-app journey above. Client additionally provides Disconnect this device because removing one device's Sync connection is useful and is not presented as an account sign-out. Neither action deletes graphs, revokes graph membership or performs an Account Reset.

Moving between the apps

The three managed apps use one global header pattern, and it carries cross-app destinations only, in this order: Account, Sync Server, then Graphs. An app's own signed-in home is never in this tier; it belongs to that app's section navigation.

App	Global links inside the app	Global links on its public pages
EtherPK Account site	Account, Sync Server, Graphs	Sync Server, Graphs
Hosted Client	Account, Sync Server, Graphs	Sync Server, Graphs
Managed Sync Server	Account, Sync Server, Graphs	Sync Server, Graphs

Account needs an account to open, so the public pages offer it only once you are signed in.

Client and Server point Account to the EtherPK Account site. The Account site and Server point Graphs to the hosted Client, while the Account site and Client point Sync Server to the managed Server. In the managed service these destinations use app.etherpk.com, server.etherpk.com and www.etherpk.com. A private deployment uses only the operator's configured origins.

The public landing page is /home on all three sites. You can open it directly while signed in. The Account site sends signed-in root visits to Account, while the managed Server sends them to Dashboard. Signed-out root visits open Home on those two sites. Client root visits resume your work instead: they open the last graph you used on this device, or the only one you have, and fall back to Graphs when there is nothing to resume. Old /marketing links continue to work by redirecting to /home.

The Client header's Graphs link also carries a menu listing the graphs on this device, so you can switch between them from anywhere in the app without going through the picker first. The list is per-device, like the graphs themselves.

App-specific destinations live in section navigation, never in the global header. The Account site keeps Account, Billing and administration there. The Server keeps its Dashboard there, alongside its other local sections. The Client has no dashboard: Graphs is its signed-in home. The Account site and managed Server show their local section navigation below the full-width global header on desktop; on smaller screens both tiers share the header's single navigation menu.

The Account site, Client and Server also show signed-in status in the header. The status uses the account's email address, shortened to 28 characters with ... when it would overflow. Open it to see the full address and the destinations which belong to that identity. Client reads this status from the active Sync connection rather than another app's browser cookie. A Custom server connection can provide its own Account and Access tokens destinations through the account menu. In standalone mode the global links are Sync Server, then Graphs, both inside the application and on public pages. A standalone Server also keeps Dashboard, Account, Access tokens and local administration in its own section navigation.

These links do not share sessions or infer sibling hostnames. Each deployment supplies the other app's exact public origin. Following a link may therefore show a different sign-in state until that app has established its own session.

The Client also separates locally cached Server graphs and unlocked vault keys by the authenticated Server account. If you switch accounts, the previous account's synced graph names and keys are hidden. Filesystem graphs remain visible because they belong to the device rather than a Server account. After upgrading from the earlier unscoped cache, EtherPK adopts a cached Server graph only after the signed-in account proves membership. You may be asked for the Recovery Code once because an old unscoped cached vault key cannot safely be assigned to either account.

Your own Sync Server

Open Sync settings and choose Custom server when you or your organisation operates the server. Enter its URL and a Personal Access Token created in that server's account portal.

A standalone-only Client may open directly on this form with its Server address already filled in. In that deployment, Managed Sync is intentionally absent rather than pointing at another service.

Standalone servers own their registration, passwords, MFA, passkeys and any social providers the operator has configured. They do not contact EtherPK's managed account service and do not need Stripe. The server operator may run with no limits or configure local limits.

The operator may also limit new registrations to exact IP addresses. A blocked visitor sees a warning on the registration page, and the Server rejects account creation even if someone calls the auth API directly. Existing users may continue to sign in from other addresses. See Self Hosting The Sync Server for REGISTRATION_ALLOWED_IPS and the trusted reverse-proxy configuration. Managed Sync does not apply this Server setting because Corporate owns managed account registration.

Standalone browser and Client authentication

The standalone Server portal also shows who is signed in. That status comes from the Server's local account session. Client custom-server connections continue to use a Personal Access Token, so signing in to the Server portal and connecting Client are separate actions.

sequenceDiagram
    actor You
    box rgb(240, 253, 244) Self-hosted Sync Server app - your server origin
        participant Portal as Browser-facing account portal
        participant Server as Local auth and Sync API
    end
    box rgb(239, 246, 255) EtherPK Client app
        participant Client as Custom-server connection
    end

    You->>Portal: Register or sign in locally
    Portal->>Server: Create a local browser session
    Server-->>Portal: Show the signed-in account
    You->>Server: Create a Personal Access Token
    Server-->>You: Display the token once
    You->>Client: Enter the Server URL and token
    Client->>Server: Authenticate Sync requests with the token
    Server-->>Client: Return this Principal's graphs and status
    Client-->>You: Show the confirmed identity in top navigation
    opt Sign out of the Server portal
        You->>Portal: Sign out
        Portal->>Server: End local browser session
        Server-->>Portal: Show Server signed out
        Note over Client,Server: Client PAT remains active until disconnected or revoked
    end
    opt Disconnect Client
        You->>Client: Remove Custom server connection
        Client->>Client: Forget local PAT configuration
        Note over Portal,Client: Server browser session is unchanged
    end

There is no cross-application sign-out in standalone mode. The Server can clear only its local browser session, while Client uses a separately revocable PAT. Client's account menu shows the PAT-confirmed email plus links to that Server's Account and Access tokens pages. Disconnect this device removes the PAT from Client without ending the Server portal session or revoking the token. Client returns to Graphs so the current workspace and its live Sync connection are closed. Revoke the PAT from Access tokens when that device or automation must lose Sync access completely.

Operators of the official hosted service can find the complete environment, external-service and rollout checklist in Managed Service Production Configuration. Self-hosters should use Self Hosting The Sync Server.

If an expected GitHub or Google button is absent, that provider has not been enabled on the custom server. Ask its operator for the correct login method. A provider with only half its credentials configured will not start, rather than showing a broken button.

When a managed write is refused

Managed Sync can refuse new growth because the Billing Account is read-only or because its graph, storage, asset or Player allowance has been reached. EtherPK treats this as a policy outcome, not as lost work:

The local edit and encrypted outbox entry remain on the device.
Reads, export, graph or asset deletion and other usage-reducing work remain available.
The Owner can reduce usage, wait for a plan change to arrive, or choose a larger plan.
Reconnecting retries the same operation safely.

Players use the Owner's allowance when writing to that Owner's graph. A Player does not consume an owned graph slot simply by joining it.

Three different account actions

Cancel subscription stops renewal. Your owned graphs go read-only at the end of the paid period and are deleted from the managed service after a retention period; your EtherPK Account and your local graphs are untouched.
Delete EtherPK Account disables the managed sign-in identity and begins a separate account lifecycle with export / transfer choices.
Account Reset is the destructive cryptographic recovery action used after losing every unlocked device and the Recovery Code. It is not a billing or sign-out action.

See Synced Graphs And Your Recovery Code for why EtherPK cannot recover encrypted knowledge when both your devices and Recovery Code are lost.