Skip to Content
Authentication Guide

Last Updated: 3/13/2026

Authentication Guide

Pie supports SSH-based authentication for securing client connections to the server. When enabled, only authorized users with registered SSH keys can submit and run inferlets.

Enabling Authentication

To enable authentication, set enable_auth = true in your configuration file:

# ~/.pie/config.toml
enable_auth = true

Restart the Pie server for the change to take effect.

Managing Authorized Users

Authorized users and their SSH public keys are stored in ~/.pie/authorized_users.toml.

File Format

The authorized users file uses TOML format with the following structure:

[users.alice.keys]
laptop = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFq... alice@laptop"
desktop = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGh... alice@desktop"
 
[users.bob.keys]
workstation = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJk... bob@work"

Each user can have multiple named keys. The key name (e.g., laptop, desktop) is for your reference only.

Adding Users via CLI

Use the pie auth command to manage authorized users:

# Add a new user with their public key
pie auth add alice ~/.ssh/id_ed25519.pub
 
# Add a named key for an existing user
pie auth add alice --key-name laptop ~/.ssh/id_ed25519.pub
 
# List all authorized users
pie auth list
 
# Remove a user
pie auth remove alice
 
# Remove a specific key
pie auth remove alice --key-name laptop

Adding Users Manually

You can also edit ~/.pie/authorized_users.toml directly:

  1. Generate an SSH key pair (if you don’t have one):

    ssh-keygen -t ed25519 -C "your_email@example.com"

  2. Copy your public key:

    cat ~/.ssh/id_ed25519.pub

  3. Add it to the authorized users file:

    [users.your_username.keys]
my_key = "ssh-ed25519 AAAAC3... your_email@example.com"

Client Authentication

When authentication is enabled, clients must provide their private key when connecting:

Python Client

from pie_client import Client
 
# Authenticate with SSH key
client = Client(
    host="localhost",
    port=8080,
    ssh_key_path="~/.ssh/id_ed25519"
)
 
# Submit an inferlet
result = client.run("text-completion", prompt="Hello, world!")

JavaScript Client

import { Client } from '@pie-project/client';
 
const client = new Client({
  host: 'localhost',
  port: 8080,
  sshKeyPath: '~/.ssh/id_ed25519'
});
 
const result = await client.run('text-completion', { 
  prompt: 'Hello, world!' 
});

Rust Client

use pie_client::Client;
 
let client = Client::builder()
    .host("localhost")
    .port(8080)
    .ssh_key_path("~/.ssh/id_ed25519")
    .build()?;
 
let result = client.run("text-completion", &json!({
    "prompt": "Hello, world!"
}))?;

Internal Authentication Token

When the Pie server starts, it generates an internal authentication token. This token is used for server-to-worker communication and is printed at startup:

[PIE] Server started at http://127.0.0.1:8080
[PIE] Internal token: pie_internal_abc123...

The internal token is also accessible via the ServerHandle in Python:

from pie import start_server, ServerConfig
 
config = ServerConfig(
    host="127.0.0.1",
    port=8080,
    enable_auth=True,
    cache_dir="~/.pie/cache",
    verbose=True,
    log_dir="~/.pie/logs",
    registry="~/.pie/registry"
)
 
handle = start_server(config)
print(f"Internal token: {handle.internal_token}")

Security Considerations

Key Management

  • Use Ed25519 keys: Modern and secure (recommended over RSA)
  • Protect private keys: Never share your private key or commit it to version control
  • Use key passphrases: Add an extra layer of security to your private keys
  • Rotate keys regularly: Remove old or compromised keys from authorized_users.toml

Network Security

  • Bind to localhost: For local development, use host = "127.0.0.1" to prevent external access
  • Use firewalls: Restrict access to the Pie port (default: 8080) at the network level
  • Enable TLS: For production deployments, use a reverse proxy (e.g., nginx) with TLS termination

User Isolation

Pie does not provide user-level isolation for inferlets. All authenticated users have equal access to:

  • Submit and run inferlets
  • Access registered models
  • Consume server resources

For multi-tenant deployments, consider:

  • Running separate Pie instances per tenant
  • Using container orchestration (e.g., Kubernetes) for isolation
  • Implementing application-level access control in your inferlets

Troubleshooting

”Authentication failed” error

Cause: The client’s SSH key is not in the authorized users file.

Solution: Add the user’s public key to ~/.pie/authorized_users.toml:

pie auth add username ~/.ssh/id_ed25519.pub

“Permission denied (publickey)” error

Cause: The client is using the wrong private key or the key file has incorrect permissions.

Solution:

  1. Verify the key path is correct
  2. Check file permissions (private key should be 600): 
    chmod 600 ~/.ssh/id_ed25519

Server doesn’t enforce authentication

Cause: enable_auth is not set to true in the configuration file.

Solution: Edit ~/.pie/config.toml and restart the server:

enable_auth = true

Example: Multi-User Setup

Here’s a complete example for a team of three users:

# ~/.pie/authorized_users.toml
 
[users.alice.keys]
laptop = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFq4... alice@laptop"
server = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGh7... alice@server"
 
[users.bob.keys]
workstation = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJk8... bob@work"
 
[users.charlie.keys]
macbook = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILm9... charlie@macbook"

Each user can connect using their respective private key. If a user’s key is compromised, remove it from the file and they will immediately lose access.

Deployment Guide