Session State & TTL

Figranium manages two distinct types of session state: dashboard sessions (your login to the Figranium UI) and browser sessions (the cookies and storage used by your automation tasks). Each has its own lifetime and storage mechanism.

Dashboard Sessions

When you log in to the Figranium dashboard, a server-side session is created and stored in data/sessions/.

Session Lifetime (TTL)

Property	Value
Session TTL	7 days of inactivity
Rolling TTL	Yes — every request resets the 7-day countdown
Session reaping	Every 1 hour (expired session files are deleted)

Sessions are rolling: the 7-day TTL resets on every authenticated request. A session only expires if you are completely inactive for 7 consecutive days. These values come from src/server/constants.js:

SESSION_TTL_SECONDS = 7 * 24 * 60 * 60  // 604,800 seconds

And are applied in the session store setup in server.js:

const sessionStore = new FileStore({
    path: SESSIONS_DIR,
    ttl: SESSION_TTL_SECONDS,   // 7 days
    reapInterval: 3600,         // clean up expired files every hour
});

app.use(session({
    store: sessionStore,
    rolling: true,              // reset TTL on every request
    cookie: {
        maxAge: SESSION_TTL_SECONDS * 1000,
        sameSite: 'strict',
        secure: SESSION_COOKIE_SECURE,
    },
}));

Session Secret and Persistence Across Restarts

The session secret is used to sign session cookies. If it changes, all existing sessions are immediately invalidated. By default, Figranium:

Reads the secret from SESSION_SECRET in your .env file.
Falls back to reading from data/session_secret.txt (auto-generated on first run and persisted there).
Generates a new random secret if neither exists.

For persistent sessions across server restarts, set a static secret in .env:

SESSION_SECRET=your-long-random-secret-here

Without this, restarting the server may generate a new secret and log out all users.

Setting	Env Variable	Default	Notes
HTTPS-only cookie	`SESSION_COOKIE_SECURE`	`false`	Set `true` when running behind HTTPS
SameSite policy	(fixed)	`strict`	Protects against CSRF

Set SESSION_COOKIE_SECURE=true in your .env when Figranium is served over HTTPS. If this is true but you access via plain HTTP, the browser will reject the cookie and you will appear logged out immediately.

Browser Session State (Cookies & Storage)

Browser session state refers to the cookies, local storage, and other browser data accumulated during task automation. This is separate from the dashboard login session.

Persistent Mode (Default)

Each execution mode maintains its own isolated browser profile directory on disk:

Execution Mode	Profile Directory
Agent	`data/browser-profile`
Scrape	`data/browser-profile-scrape`
Headful/VNC	`data/browser-profile-headful`

Cookies in these profiles have no platform-imposed TTL — they persist indefinitely unless:

The cookie’s own Expires / Max-Age attribute causes it to expire.
You manually clear cookies in Settings > Data.
You click Clear Storage to wipe all session data.

Stateless Mode

When statelessExecution: true is set on a task, Figranium launches an ephemeral in-memory browser context. No profile directory is read from or written to. All cookies and storage generated during the run are discarded immediately when the task completes. See Stateless Execution for full details.

Named Session Snapshots (`sessionId`)

For workflows that need multiple isolated logged-in identities on the same target — for example, one automation per customer account, or a shared account per team — pass a sessionId on the run. Figranium stores that run’s cookies and local storage in a dedicated snapshot file, keyed by name, and reloads it on every subsequent run that passes the same sessionId. Snapshots are written to:

data/sessions/<sessionId>.json

How it works:

On task start, if sessionId is provided and a snapshot file exists, Figranium loads it into the browser context as the initial storageState (cookies + localStorage).
The task runs against that pre-loaded state — logged-in sessions from earlier runs with the same sessionId are already available.
On successful completion, the browser’s current storage state is written back to the same snapshot file, so any new cookies or refreshed tokens are captured for next time.

Naming rules: sessionId is sanitized to [a-zA-Z0-9_-] before use. Any other characters are stripped. If the sanitized name is empty, no snapshot is loaded or saved. Keep names short and predictable — for example acct-alice, acct-bob, tenant_42. When to use it vs. the default profile directory:

Situation	Use
A single logged-in identity per execution mode	Default profile directory (nothing to configure)
Multiple accounts on the same site, one per run	`sessionId` per account
Per-tenant or per-customer automations	`sessionId` per tenant
Fresh browser every time	`statelessExecution: true`

Example — trigger a task with a specific session identity:

curl -X POST http://localhost:11345/api/tasks/task_1/api \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_key" \
  -d '{
    "variables": { "search": "widgets" },
    "sessionId": "acct-alice"
  }'

The first run signs Alice in and saves her cookies to data/sessions/acct-alice.json. Every future run that passes "sessionId": "acct-alice" starts already signed in as Alice. Passing "sessionId": "acct-bob" on the next run instead starts a completely separate session under Bob’s cookies.

sessionId snapshots are independent of the persistent profile directories (data/browser-profile*). They are also independent of the headful cookie sync — a sessionId-driven run does not read from or write to data/headful-storage-state.json. If you set both sessionId and statelessExecution: true, the snapshot is still not persisted (stateless wins).

Cookies accumulated during a headful (VNC) browser session are shared with agent and scrape runs automatically. This is done via a JSON snapshot file:

data/headful-storage-state.json

Sync Interval

Event	Action
Every 30 seconds during an active headful session	Cookies written to `headful-storage-state.json`
On headful session close	Final write before shutdown
Agent / scrape task startup	Reads and injects cookies from `headful-storage-state.json`

The 30-second interval is set in headful.js:

const syncInterval = setInterval(() => {
    saveHeadfulStorageState(activeSession.context).catch(() => {});
}, 30000);

Before writing or injecting cookies, Figranium filters out expired ones:

const now = Date.now() / 1000;
const validCookies = cookies.filter(
    c => !c.expires || c.expires === -1 || c.expires > now
);

Only non-expired cookies are saved to the snapshot or injected into new contexts. This prevents stale authentication tokens from being replayed. Note: Cookie sync is skipped entirely for stateless runs — the sync interval is not started when statelessExecution is true.

Internal Cache TTLs

For performance, Figranium caches frequently-read data in memory with short TTLs:

Cache	TTL	What It Covers
Storage cache	5 seconds	Users, tasks, API keys read from disk/DB
Allowed IPs cache	5 seconds	Contents of `data/allowed_ips.json`

These are internal implementation details (src/server/constants.js):

STORAGE_CACHE_TTL = 5000        // 5 seconds
ALLOWED_IPS_TTL_MS = 5000       // 5 seconds

Changes to allowed IPs or tasks take effect within 5 seconds without a server restart.

Rate Limit Windows

Authentication and data API endpoints use a sliding 15-minute window:

Endpoint Type	Env Variable	Default
Login attempts	`AUTH_RATE_LIMIT_MAX`	10 per 15 min
Data API requests	`DATA_RATE_LIMIT_MAX`	100 per 15 min

Figranium previously stored cookies in a single storage_state.json file. As of v0.10.0, cookies are stored in persistent browser profile directories. On first startup after upgrading, Figranium automatically:

Reads cookies from the old storage_state.json.
Filters out any expired cookies.
Injects the valid cookies into all three profile directories.
Deletes storage_state.json.

No manual action is required. If migration fails partway through, the file is retained so the next startup can retry.

Clearing Session Data

Action	How
Clear all browser cookies	Settings > Data > Clear Storage
Copy a cookie value	Settings > Data > Cookies — click Copy next to any cookie
Delete an individual cookie	Settings > Data > Cookies — click Delete next to any cookie
Invalidate dashboard sessions	Restart server with a new `SESSION_SECRET`
Clear execution logs	Settings > Data (up to `MAX_EXECUTIONS` entries retained)

Intro

Installation

Basics

Features

Agent Logic

Integrations

API

Ops

Changelog

Dashboard Sessions

Session Lifetime (TTL)

Session Secret and Persistence Across Restarts

Browser Session State (Cookies & Storage)

Persistent Mode (Default)

Stateless Mode

Named Session Snapshots (`sessionId`)

Sync Interval

Internal Cache TTLs

Rate Limit Windows

Clearing Session Data

​Dashboard Sessions

​Session Lifetime (TTL)

​Session Secret and Persistence Across Restarts

​Cookie Security

​Browser Session State (Cookies & Storage)

​Persistent Mode (Default)

​Stateless Mode

​Named Session Snapshots (sessionId)

​Headful-to-Agent/Scrape Cookie Sync

​Sync Interval

​Expired Cookie Filtering

​Internal Cache TTLs

​Rate Limit Windows

​Cookie Migration (v0.9.6 and Earlier)

​Clearing Session Data

Dashboard Sessions

Session Lifetime (TTL)

Session Secret and Persistence Across Restarts

Cookie Security

Browser Session State (Cookies & Storage)

Persistent Mode (Default)

Stateless Mode

Named Session Snapshots (`sessionId`)

Headful-to-Agent/Scrape Cookie Sync

Sync Interval

Expired Cookie Filtering

Internal Cache TTLs

Rate Limit Windows

Cookie Migration (v0.9.6 and Earlier)

Clearing Session Data