Configuration
Configure Axil Studio - axil run defaults, every StudioServer option incl. allowedHosts, maxBodyBytes, openBrowser and cwd, and the security model.
On this page7
Under axil run Studio needs no configuration: everything comes from package.json and .env. This page covers those defaults, the options for running StudioServer yourself, and how Studio protects your machine.
Defaults under axil run
| Setting | Value |
|---|---|
port | PORT from .env (default 3000) plus 1 |
host | 127.0.0.1 |
appPort | PORT from .env, default 3000 |
appName | name from package.json, otherwise axiljs-app |
dbDriver / dbFile | sqlite and DATABASE_FILENAME, when it is set |
dbDriver / dbUrl | postgres or mysql and DATABASE_URL, picked from the URL prefix |
enableQR | true |
| Other options | Their defaults (below) |
To change the Studio port, change PORT. The CLI has no flags for the other options; use the programmatic API if you need them.
Running Studio programmatically
@axiljs/studio exports StudioServer and its types (StudioConfig, StudioData, RouteInfo, TableInfo, ColumnInfo, TableSchema, ForeignKeyInfo, IndexInfo, RowFilter, RowQuery).
1import { StudioServer } from '@axiljs/studio'
2
3const studio = new StudioServer({
4 port: 3001,
5 host: '127.0.0.1',
6 appPort: 3000,
7 appName: 'my-api',
8 dbDriver: 'sqlite',
9 dbFile: './dev.db',
10 enableQR: true,
11 openBrowser: false,
12})
13
14await studio.start()
15console.log(`Studio on port ${studio.getPort()}`)
16
17// later
18await studio.stop()Methods
| Method | Description |
|---|---|
start() | Connects to the database (retrying in the background if it isn't ready), collects data, listens, prints the URL and, unless openBrowser is false, opens the browser |
stop() | Closes the HTTP server and the database handle or pool Studio opened |
getPort() | The port actually bound (useful with port: 0) |
setDriver(driver, driverType) | Use an existing database driver instead of letting Studio connect |
StudioConfig options
portnumberrequiredPort Studio listens on. 0 picks a free port; read it with getPort().
hoststringrequiredAddress to bind, for example '127.0.0.1'. It is also always accepted as a Host header value.
appPortnumberrequiredPort of your app. The app URL, the request proxy target, the realtime URLs and the app QR code all use http://localhost: plus this port.
appNamestringrequiredShown in the sidebar, page title and breadcrumbs, and used to name exported collections.
enableQRbooleanrequiredRequired by the type. QR codes are currently always generated, so this flag does not change behavior.
dbDriverstring'sqlite', 'postgres' or 'mysql'. Without it Studio does not connect to a database.
dbFilestringdefault: './dev.db'SQLite file, resolved against cwd (absolute paths are used as-is). Opened read-only with better-sqlite3.
dbUrlstringPostgreSQL (pg) or MySQL (mysql2) connection URL.
allowedHostsstring[]default: []Extra Host header names (host name only, no port) Studio answers to, for example a LAN name. localhost, 127.0.0.1, [::1] and host are always allowed. Any other host gets 403 Invalid Host header. CORS is granted to the same set of hosts.
maxBodyBytesnumberdefault: 1048576Maximum POST body size for /api/studio/query and /api/studio/proxy (1 MB by default). Larger requests get 413.
openBrowserbooleandefault: trueOpen the Studio URL in the default browser on start().
cwdstringdefault: process.cwd()Project directory. Studio scans cwd/src for routes and resolves dbFile against it.
intentPathstringdefault: '/__axil/studio/intent'Path on the app that serves the runtime report for the Intent view. Must match intentEndpoint({ path }). New in 0.3.5.
Attaching your own driver
In a single process you can hand Studio an existing driver instead of a connection string:
studio.setDriver(driver, 'sqlite') // or 'postgres' / 'mysql'The driver must provide query(sql, params) returning { rows } (and optionally affectedRows). If it also provides queryReadOnly(sql), the SQL console uses that method; otherwise it calls query.
Warning
With your own driver, Studio's read-only transaction and read-only SQLite handle don't apply: only the statement-type and OUTFILE/DUMPFILE checks protect the database. Pass a driver on a read-only connection, or implement queryReadOnly. Under axil run this doesn't apply: your app runs in a child process, so Studio always opens its own read-only connection.
Security
Studio has no login. It is safe because it is local and read-only:
- Loopback by default:
axil runbinds Studio to127.0.0.1, so other machines can't connect. - DNS-rebinding protection: requests whose
Hostheader isn'tlocalhost,127.0.0.1,[::1], the bindhostor anallowedHostsentry are rejected with403. This stops a public website whose domain re-resolves to127.0.0.1from reading Studio. - Restricted CORS:
Access-Control-Allow-Originis only sent back to origins on those same hosts, never*. Other websites can't read Studio's responses. - Proxy guarded:
POST /api/studio/proxyonly accepts JSON bodies (which forces a CORS preflight) and only ever calls your app onlocalhost, so it can't be used to reach other hosts. - Read-only data access: the database browser only runs
SELECT/COUNT(*)with checked, quoted identifiers and bound values; the SQL console only accepts read statements and runs them read-only (see SQL console). - Body limits: POST bodies above
maxBodyBytesare rejected with413. - Safe rendering: the app name and all data are inserted as text, not HTML.
Danger
Never expose Studio on a public network or run it in production. If you bind it to a LAN address, add only names you control to allowedHosts.
Caching and refresh
- Routes and tables are collected on demand and cached for 5 seconds on the server.
GET /api/studio/dataalways re-collects.- The browser reloads data every 30 seconds while the tab is visible, and on Refresh data.
Was this page helpful?