Running the engine

Your code and the runtime communicate over a transport. The default, used by plain connect(), is a spawned child process. The other modes exist for specific situations; all carry the same protocol, so switching does not change application code.

Default: spawned child process

await client.connect();   // Bun and Python SDKs

The SDK spawns the runtime and talks JSON over the child's stdin/stdout. Properties of this mode:

• No configuration: no ports, no socket files, nothing to clean up.
• Crash isolation: if the runtime dies, your app receives a close event.
• Coupled lifecycle: the runtime shuts down when your process exits.
• Private: no other process can connect to it.

Options passed to connect become engine arguments:

await client.connect({
  stdio: { args: ["--no-project", "--bridge-window", "size=1000x700"] },
});

In-process

The runtime file is also a loadable library. In this mode the engine runs inside your process:

Bun

await client.connect({ inproc: { args: ["--no-project"] } });

Python

from godot_ui import GodotClient, InprocTransport
client = GodotClient()
client.connect(transport=InprocTransport(args=["--no-project"]))

Use it for single-file distribution (see Shipping) or where spawning processes is not possible. Trade-offs:

• An engine crash is a crash of your process.
• One engine per process, with no restart after it stops.
• The engine's frame loop must be pumped. The SDKs do this (Bun on the event loop, Python on a background thread); compiled languages write the loop themselves (see the language guides).

Attach: TCP and Unix sockets

Both modes above tie the runtime's lifetime to your process. To keep a window alive across client restarts (for example, code reload during development), or to connect several programs to one UI, start the runtime separately and attach to it:

guido --no-project --bridge-listen 127.0.0.1:9080 --bridge-token s3cret &

await client.connect({ tcp: { port: 9080 }, token: "s3cret" });

• TCP (--bridge-listen): available everywhere. Loopback only. Set --bridge-token; without it any local process can drive the UI.
• Unix socket (--bridge-socket /path): POSIX. Permissions 0600, no token needed.
• Windows named pipe (--bridge-pipe name): the Windows equivalent.

Signal subscriptions do not survive a reconnect; re-subscribe after attaching.

Inverted: the engine spawns your program

guido --spawn "python3 app.py" starts the runtime first; the runtime launches your program as its child and communicates over the child's stdio. When your program exits, the runtime quits. Use this when the executable the user launches should be the engine binary.

Summary

Mode	Processes	Lifetime coupling	Use for
spawned child (default)	2	coupled	most applications
in-process	1	one address space	single-file apps, embedding
TCP + token / Unix socket	2	independent	attach to a running UI, client restarts, multiple clients
engine-as-parent	2	coupled	engine binary as the entry point