Install the agent

The agent is one FiveM resource. It connects out to FiveDock over an encrypted websocket and does what the panel asks, as long as the command is on the list it accepts.

Nothing listens on your machine. There is no port to forward, and your database password stays where it is.

Add the resource

Download the release, drop it in resources/[fivedock] and start it before your framework. fivedock_check in the console prints what it is using.

shell

curl -fLO https://dl.fivedock.dev/agent/latest/fivedock.zip
unzip fivedock.zip -d resources/[fivedock]

server.cfg

ensure fivedock
set fivedock_key "fda_live_…"

# lets fivedock perf record FXServer’s profiler
add_ace resource.fivedock command.profiler allow
add_ace resource.fivedock command.record allow
add_ace resource.fivedock command.saveJSON allow

# optional: where uploads land, and how loud the log is
set fivedock_folder "/screenshots"
set fivedock_log "info"

fda_live_… is an agent key. You make it in the panel for one server, and it only goes in server.cfg. It is not an API token: anything that calls the upload API over HTTP uses an fd_live_… token from the Tokens page instead.

Upload something

There are two ways to upload, and both store the same file: deduplicated and billed once.

Lua

exports.fivedock:upload({
  resource = 'my-script',
  path     = 'cache/shot.jpg',
  folder   = '/screenshots',
}, function(err, file)
  if not err then print(file.url) end
end)

-- take the screenshot and upload it in one call
exports.fivedock:screenshot(source, { folder = '/screenshots', quality = 0.9 }, cb)

HTTP

curl -X POST https://api.fivedock.dev/api/v3/file \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "path=/screenshots"

The exports go through the agent and its key, so your script holds no secret. The HTTP route is the upload API, which takes an API token (fd_live_…) and never the agent key.

Server exports

The fivedock resource gives your server scripts five exports. Call them from server-side Lua: they travel over the agent’s own connection, so your script needs no token. fivedock_upload_allow decides which resources may call the upload ones.

screenshot

Takes a screenshot of a player and uploads it. screenshot-basic has to be started. folder is where it lands, fivedock_folder by default; encoding is jpg, png or webp, jpg by default; and quality runs from 0 to 1, 0.85 by default.

Lua

-- server.lua: /evidence <player id> screenshots that player, for staff only
RegisterCommand('evidence', function(source, args)
  local target = tonumber(args[1])
  if not target then return end

  exports.fivedock:screenshot(target, {
    folder   = '/evidence',
    encoding = 'webp', -- 'jpg' (default), 'png' or 'webp'
    quality  = 0.85,   -- 0 to 1
  }, function(err, file)
    if err then
      print(('screenshot failed: %s'):format(err))
      return
    end
    print(('%s, %d bytes, %s'):format(file.url, file.size, file.mimeType))
  end)
end, true)

upload

Uploads a file from a resource’s folder. resource is the resource that calls the export unless you name another, path is relative to that resource’s folder, name sets the file name and folder the folder it lands in.

Lua

-- a file your resource wrote to resources/my-script/cache/shot.jpg
exports.fivedock:upload({
  resource = 'my-script',      -- defaults to the resource calling the export
  path     = 'cache/shot.jpg', -- relative to that resource's folder
  name     = 'shot.jpg',
  folder   = '/screenshots',
}, function(err, file)
  if not err then print(file.url) end
end)

uploadFile

The same upload, with the resource and the path as arguments of their own.

Lua

exports.fivedock:uploadFile('my-script', 'cache/shot.jpg', {
  name   = 'shot.jpg',
  folder = '/screenshots',
}, function(err, file)
  if not err then print(file.id, file.url) end
end)

The callback

Each upload export calls cb(err, file) once. On success err is nil and file is a table with id, url, size and mimeType. On failure err is a string that says why, and file is nil.

Lua

function(err, file)
  -- on success: err = nil
  --   file = { id = '8Kq2nR4t', url = 'https://cdn.fivedock.dev/f/8Kq2nR4t.jpg',
  --            size = 48213, mimeType = 'image/jpeg' }
  -- on failure: err = 'screenshot-basic is not started' (or another reason), file = nil
end

report

Files a player report that the staff on duty see in the panel. source is the player reporting, message says what happened, and subjectSource, if you pass it, is the player being reported. It returns true, or false and a reason: empty when the message is shorter than 3 characters, too_soon within 30 seconds of that player’s last report.

Lua

-- source reports subjectSource; subjectSource is optional
local ok, reason = exports.fivedock:report(source, 'He rammed my car at Legion Square', 12)
if not ok then
  print(('report refused: %s'):format(reason)) -- 'empty' or 'too_soon'
end

log

Writes an event to the Black Box. source is the player it is about, or 0 for none; event is a dotted name such as money.transfer; meta is an optional table of fields, and a numeric amount in it counts toward the economy alerts. The agent already records joins and drops, deaths, chat, ESX and QBCore money changes, ox_inventory moves and txAdmin bans, kicks and warns by itself, so this export is for what only your scripts know.

Lua

-- source is the player it is about, or 0; meta is optional
exports.fivedock:log(source, 'money.transfer', 'Paid 500 to Bo for the car', {
  amount = 500, to = 'license:9a4f…',
})

Find what lags

The add_ace lines let the agent record FXServer’s profiler, for fivedock perf and for the stalls it catches by itself. Find what lags shows how to read what it finds.

Settings

Convar	Default	What it does
fivedock_key	Default · -	Required. The agent key, `fda_live_…`, made in the panel, one per server. The agent refuses to start without it, and the upload API does not accept it.
fivedock_gateway	Default · ours	Where the agent connects. wss:// only, except against localhost.
fivedock_folder	Default · /	Default folder for uploads.
fivedock_upload_allow	Default · all	Which resources may call the upload exports. Empty means all of them.
fivedock_log	Default · info	info or debug. debug never prints a credential.

Next: move your city over