guide documentation

[[goblin-host]]

Goblin Host

By Goblin Docs ~ 8 min read

Goblin includes a built-in HTTP server called Goblin Host.

It can:

serve static files
run action APIs
proxy requests to other services
host multiple sites from a single process

Goblin Host is primarily used for local development, but it can also run in production environments.

Starting the Server

The server starts with the start command.

Default port

goblin start

By default the server listens on:

http://localhost:5173

Tip

If another development server is already using the default port, you can run Goblin Host on a different port using --port.

Custom port

You can specify a port:

goblin start --port 4242

Example:

http://localhost:4242

Static File Serving

Goblin Host serves files from the docroot.¹

The docroot defaults to the current working directory when the server starts.

Example:

site/
  index.html
  docs/
    guide.html

If you start the server inside site:

cd site
goblin start

Then these URLs work:

http://localhost:5173/
http://localhost:5173/docs/guide.html

Docroot

The docroot can also be set with an environment variable:

GOBLIN_DOCROOT

Example:

Windows PowerShell

$env:GOBLIN_DOCROOT="dist"
goblin start

macOS / Linux

GOBLIN_DOCROOT=dist goblin start

Goblin Host will then serve files from that directory regardless of where the command is executed.

API Execution

Goblin Host can execute action files as HTTP endpoints.

In Goblin, this happens when a request is made to a path inside /api.

For example, if your project contains:

api/
  passwords.gbln

and the server is running, visiting:

http://localhost:5173/api/passwords

will execute:

api/passwords.gbln

The output of that script becomes the HTTP response.

This means Goblin follows a very simple rule:

/api/<name>  ->  api/<name>.gbln  ->  execute

Warning

Goblin only executes scripts inside the api/ folder.

If a .gbln file exists anywhere else in your project (for example docs/passwords.gbln), Goblin Host treats it as a static file and will serve or download it instead of executing it.

Note

A static file is something Goblin Host sends.

An API script is something Goblin Host runs.

So the real distinction is:

files inside api/ are treated as executable server scripts
files outside api/ are treated as static site content

This lets Goblin keep a clear boundary between:

site files
server logic

This allows Goblin projects to implement:

dynamic endpoints
server-side utilities
development tooling
lightweight APIs

Proxy Rules

Goblin Host can forward requests to other services using proxy rules.

This is useful when combining Goblin with:

databases
external APIs
development servers
frontend tooling

Safety

Goblin Host protects the filesystem by preventing path traversal.

Requests such as:

../../secret.txt

are blocked and cannot escape the docroot.

This ensures the server only exposes files inside the configured site directory.

Development Workflow

A typical development workflow might look like:

goblin build
cd dist
goblin start --port 4242

You can then open the site in your browser and inspect the generated output.

Why Goblin Host Exists

Goblin Host provides a zero-configuration development server.

Instead of installing additional web servers, Goblin projects can immediately:

preview generated sites
run APIs
test integrations
debug builds

All using the same toolchain that produced the site.

The docroot is the directory the server treats as the root of the website. ↩