Configuration

Studio is designed to work with zero configuration. Everything it needs is read from your existing .env file. This page documents all available options for advanced use cases.

Default Behaviour

When you run axil run, Studio:

Reads PORT from .env (default: 3000)
Starts on PORT + 1 (default: 3001)
Reads DATABASE_URL or DATABASE_FILENAME from .env
Connects to the database in read-only mode
Opens your browser to http://localhost:3001

Environment Variables

These variables are read from your project .env file:

Variable	Description	Example
`PORT`	Your app port. Studio uses `PORT + 1`	`3000`
`DATABASE_FILENAME`	SQLite database file path	`./dev.db`
`DATABASE_URL`	PostgreSQL or MySQL connection URL	`postgres://user:pass@localhost/db`

StudioServer Options

If you use Studio programmatically, the StudioServer constructor accepts:

typescript

import { StudioServer } from '@axiljs/studio'
 
const studio = new StudioServer({
  port:     3001,          // Studio port
  host:     '127.0.0.1',  // Bind address
  appPort:  3000,          // Your application port
  appName:  'my-api',     // Display name in the sidebar
  dbDriver: 'sqlite',     // 'sqlite' | 'postgres' | 'mysql' | undefined
  dbFile:   './dev.db',   // SQLite file path
  dbUrl:    undefined,    // PostgreSQL or MySQL URL
  enableQR: true          // Generate QR codes
})
 
await studio.start()

Attaching a Live Driver

If you want Studio to share your application's existing database connection (only possible in the same process):

typescript

import { StudioServer } from '@axiljs/studio'
import { createConnection } from '@axiljs/orm'
 
const db = await createConnection({ driver: 'sqlite', filename: './dev.db' })
 
const studio = new StudioServer({ port: 3001, appPort: 3000, appName: 'my-api' })
 
// Attach the live driver
studio.setDriver(db.getDriver(), 'sqlite')
 
await studio.start()

Info

In normal axil run usage, Studio runs in the CLI process and your app runs in a child process. Studio cannot share the app's driver and instead opens its own read-only connection.

Changing the Studio Port

Studio always uses APP_PORT + 1. To change the Studio port, change your app port:

env

# .env
PORT=8080
# Studio will use 8081

Disabling Auto-Open

Studio opens a browser window automatically. To prevent this, set STUDIO_NO_OPEN in your environment:

Terminal

STUDIO_NO_OPEN=1 axil run

Warning

This environment variable is checked by the openBrowser() method in the Studio server. Make sure you are on CLI version 0.2.2 or later.

Disabling Studio Entirely

Studio is loaded as an optional dependency. If @axiljs/studio is not installed, the CLI silently skips it and your dev server starts normally:

Terminal

npm uninstall @axiljs/studio

axil run

# Studio unavailable — dev server starts normally

Security

Studio is intended for local development only:

It binds to 127.0.0.1 by default (not accessible from the network)
The SQL editor only allows read-only queries
Database connections use read-only mode where supported
No authentication is required (rely on the loopback interface for security)

Never expose Studio to a public network or production environment.

Studio sets permissive CORS headers on all /api/studio/* endpoints to allow the browser to fetch data from the Studio server. These headers are only present on Studio API routes, not on your application routes.

Cache

Studio caches the collected route and table data for 5 seconds. When you click Refresh in the UI or when the 30-second auto-refresh fires, the cache is cleared and data is re-collected from disk.