How to Manage Users in Pi-Web: Single-User Architecture and External Provider Authentication

Pi-Web operates as a single-user local application without built-in user account management, relying instead on OS-level permissions for access control and dedicated API routes to manage external AI provider credentials.

Pi-Web, developed by agegr/pi-web, is a local front-end for the Pi AI engine designed to run under a single operating system user. Unlike traditional web applications, managing users in Pi-web does not involve creating internal accounts or permissions databases. Instead, user management focuses on securing access to the host system and administering credentials for external AI providers through specific authentication endpoints.

Understanding Pi-Web's Single-User Architecture

Pi-Web does not implement a multi-user system or maintain a database of user accounts. The only "user" concept in the codebase appears as the message role (e.g., user, assistant) used to distinguish human input from AI output in conversation threads. In hooks/useAgentSession.ts, the application tracks messages where msg.role === "user" to drive UI updates and session statistics defined in lib/pi-types.ts, but these represent conversation participants rather than authenticated accounts.

The application runs under the current operating system user, with all filesystem access and process permissions governed by the OS itself. This design eliminates the need for internal user management but requires administrators to control access at the system level.

Managing External AI Provider Credentials

Since Pi-Web delegates authentication to external AI services, managing users effectively means managing these provider connections. The application stores and accesses provider credentials through dedicated API routes under /api/auth.

Storing API Keys

The app/api/auth/api-key/[provider]/route.ts endpoint handles adding, retrieving, and deleting API-key credentials. To store a new key:

POST /api/auth/api-key/openai
Content-Type: application/json

{
  "apiKey": "sk‑YOUR_OPENAI_KEY"
}

OAuth Authentication Flow

For providers supporting OAuth, the app/api/auth/login/[provider]/route.ts implements the device-code flow. Initiate authentication with:

POST /api/auth/login/openai

Checking Provider Status

Verify which providers are configured and their authentication status using the app/api/auth/all-providers/route.ts endpoint:

GET /api/auth/all-providers

Revoking Credentials

Remove stored API keys when access should be terminated:

DELETE /api/auth/api-key/openai

Security Controls and Request Validation

While Pi-Web lacks internal user accounts, it implements security through lib/request-security.ts, which validates that only allowed origins and request parameters are accepted. This prevents unauthorized requests to the authentication endpoints. All credential storage occurs locally on the machine, protected by the operating system's filesystem permissions rather than application-layer access controls.

Extending Pi-Web for Multi-User Environments

If your deployment requires true multi-user functionality with separate login accounts, Pi-Web requires additional infrastructure. You must implement a reverse proxy with authentication or a custom wrapper that stores per-user session data externally. The base application in agegr/pi-web assumes single-operator use and does not provide hooks for user isolation or session management between distinct human users.

Summary

• Pi-Web operates as a single-user application without internal user account databases or multi-user authentication.
• OS-level permissions control access to the application and its data, as the server runs under the current system user.
• External AI credentials are managed via /api/auth endpoints in app/api/auth/api-key/[provider]/route.ts and app/api/auth/login/[provider]/route.ts.
• The message role concept in hooks/useAgentSession.ts tracks conversation participants for UI purposes, not authenticated users.
• Multi-user setups require external infrastructure such as reverse proxies with authentication layers.

Frequently Asked Questions

Does Pi-Web support multiple user accounts?

No, Pi-Web does not implement a multi-user system or user account database. It runs as a single-user local application under the current operating system user, tracking only message roles (user vs assistant) in lib/pi-types.ts for conversation context rather than authentication.

Where are AI provider credentials stored in Pi-Web?

Credentials are stored and managed through the API routes defined in app/api/auth/api-key/[provider]/route.ts for API keys and app/api/auth/login/[provider]/route.ts for OAuth flows. The lib/request-security.ts module validates all incoming requests to these endpoints, while the actual credential data resides on the local filesystem protected by OS permissions.

How do I secure Pi-Web if multiple people use the same computer?

Since Pi-Web relies on OS-level access controls rather than application-layer user management, secure the host system by restricting which operating system users can execute the server or access the application directory. For network deployments requiring distinct user sessions, place Pi-Web behind a reverse proxy with authentication to handle multi-user access before requests reach the application.

What is the difference between the "user" role and user accounts in Pi-Web?

The "user" role in Pi-Web refers to the message type tracked in hooks/useAgentSession.ts to distinguish human input from AI responses in conversation statistics. This is purely a conversation construct used for UI updates and session metrics, not an authentication or account management feature.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}